From cf7abb4a0ad6a6de3acf3215ca6d31fdebbf4708 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Sat, 1 Nov 2014 23:27:29 +0000 Subject: restructure urldb source remove forward declarations and restructure. exported functions are also now documented in the urldb.h header. --- content/urldb.h | 216 +++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 208 insertions(+), 8 deletions(-) (limited to 'content/urldb.h') diff --git a/content/urldb.h b/content/urldb.h index c0fece24e..d7ca8b0f8 100644 --- a/content/urldb.h +++ b/content/urldb.h @@ -64,62 +64,262 @@ struct cookie_data { struct bitmap; -/* Destruction */ +/** + * Destroy urldb + */ void urldb_destroy(void); + /* Persistence support */ + +/** + * Import an URL database from file, replacing any existing database + * + * \param filename Name of file containing data + */ nserror urldb_load(const char *filename); -void urldb_save(const char *filename); + +/** + * Export the current database to file + * + * \param filename Name of file to export to + */ +nserror urldb_save(const char *filename); + +/** + * Set the cross-session persistence of the entry for an URL + * + * \param url Absolute URL to persist + * \param persist True to persist, false otherwise + */ void urldb_set_url_persistence(nsurl *url, bool persist); + /* URL insertion */ + +/** + * Insert an URL into the database + * + * \param url Absolute URL to insert + * \return true on success, false otherwise + */ bool urldb_add_url(nsurl *url); /* URL data modification / lookup */ + +/** + * Set an URL's title string, replacing any existing one + * + * \param url The URL to look for + * \param title The title string to use (copied) + */ void urldb_set_url_title(nsurl *url, const char *title); + +/** + * Set an URL's content type + * + * \param url The URL to look for + * \param type The type to set + */ void urldb_set_url_content_type(nsurl *url, content_type type); + +/** + * Update an URL's visit data + * + * \param url The URL to update + */ void urldb_update_url_visit_data(nsurl *url); + +/** + * Reset an URL's visit statistics + * + * \param url The URL to reset + */ void urldb_reset_url_visit_data(nsurl *url); + +/** + * Find data for an URL. + * + * \param url Absolute URL to look for + * \return Pointer to result struct, or NULL + */ const struct url_data *urldb_get_url_data(nsurl *url); + +/** + * Extract an URL from the db + * + * \param url URL to extract + * \return Pointer to database's copy of URL or NULL if not found + */ nsurl *urldb_get_url(nsurl *url); + /* Authentication modification / lookup */ -void urldb_set_auth_details(nsurl *url, const char *realm, - const char *auth); + +/** + * Set authentication data for an URL + * + * \param url The URL to consider + * \param realm The authentication realm + * \param auth The authentication details (in form username:password) + */ +void urldb_set_auth_details(nsurl *url, const char *realm, const char *auth); + +/** + * Look up authentication details in database + * + * \param url Absolute URL to search for + * \param realm When non-NULL, it is realm which can be used to determine + * the protection space when that's not been done before for given URL. + * \return Pointer to authentication details, or NULL if not found + */ const char *urldb_get_auth_details(nsurl *url, const char *realm); + /* SSL certificate permissions */ + +/** + * Set certificate verification permissions + * + * \param url URL to consider + * \param permit Set to true to allow invalid certificates + */ void urldb_set_cert_permissions(nsurl *url, bool permit); + +/** + * Retrieve certificate verification permissions from database + * + * \param url Absolute URL to search for + * \return true to permit connections to hosts with invalid certificates, + * false otherwise. + */ bool urldb_get_cert_permissions(nsurl *url); + /* Thumbnail handling */ + +/** + * Set thumbnail for url, replacing any existing thumbnail + * + * \param url Absolute URL to consider + * \param bitmap Opaque pointer to thumbnail data, or NULL to invalidate + */ void urldb_set_thumbnail(nsurl *url, struct bitmap *bitmap); + +/** + * Retrieve thumbnail data for given URL + * + * \param url Absolute URL to search for + * \return Pointer to thumbnail data, or NULL if not found. + */ struct bitmap *urldb_get_thumbnail(nsurl *url); + /* URL completion */ + +/** + * Iterate over entries in the database which match the given prefix + * + * \param prefix Prefix to match + * \param callback Callback function + */ void urldb_iterate_partial(const char *prefix, - bool (*callback)(nsurl *url, - const struct url_data *data)); + bool (*callback)(nsurl *url, const struct url_data *data)); + /* Iteration */ + +/** + * Iterate over all entries in database + * + * \param callback Function to callback for each entry + */ void urldb_iterate_entries(bool (*callback)(nsurl *url, const struct url_data *data)); + +/** + * Iterate over all cookies in database + * + * \param callback Function to callback for each entry + */ void urldb_iterate_cookies(bool (*callback)(const struct cookie_data *cookie)); -/* Debug */ -void urldb_dump(void); /* Cookies */ + +/** + * Parse Set-Cookie header and insert cookie(s) into database + * + * \param header Header to parse, with Set-Cookie: stripped + * \param url URL being fetched + * \param referer Referring resource, or 0 for verifiable transaction + * \return true on success, false otherwise + */ bool urldb_set_cookie(const char *header, nsurl *url, nsurl *referer); + +/** + * Retrieve cookies for an URL + * + * \param url URL being fetched + * \param include_http_only Whether to include HTTP(S) only cookies. + * \return Cookies string for libcurl (on heap), or NULL on error/no cookies + */ char *urldb_get_cookie(nsurl *url, bool include_http_only); + +/** + * Delete a cookie + * + * \param domain The cookie's domain + * \param path The cookie's path + * \param name The cookie's name + */ void urldb_delete_cookie(const char *domain, const char *path, const char *name); + +/** + * Load a cookie file into the database + * + * \param filename File to load + */ void urldb_load_cookies(const char *filename); + +/** + * Save persistent cookies to file + * + * \param filename Path to save to + */ void urldb_save_cookies(const char *filename); +/* Debug */ + +/** + * Dump URL database to stderr + */ +void urldb_dump(void); + + /* test harness only */ + +/** + * Add a host to the database, creating any intermediate entries + * + * \param host Hostname to add + * \return Pointer to leaf node, or NULL on memory exhaustion + */ struct host_part *urldb_add_host(const char *host); + +/** + * Add a path to the database, creating any intermediate entries + * + * \param scheme URL scheme associated with path + * \param port Port number on host associated with path + * \param host Host tree node to attach to + * \param path_query Absolute path plus query to add (freed) + * \param fragment URL fragment, or NULL + * \param url URL (fragment ignored) + * \return Pointer to leaf node, or NULL on memory exhaustion + */ struct path_data *urldb_add_path(lwc_string *scheme, unsigned int port, const struct host_part *host, char *path_query, lwc_string *fragment, nsurl *url); -- cgit v1.2.3