mirrors/netsurf
1
0
Fork 0
mirror of https://github.com/netsurf-browser/netsurf synced 2024-12-25 21:46:57 +03:00
Code Issues Packages Projects Releases Wiki Activity

clean up content headers and documentation comments

Browse Source 
pure formatting and documentation changes, no code difference
This commit is contained in:
Vincent Sanders 2020-05-06 23:38:50 +01:00
parent c2f9bcac19
commit 5f8b1497e1
11 changed files with 672 additions and 455 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

667
content/content.c
View File

File diff suppressed because it is too large Load Diff

200
content/content.h
View File

@ -287,41 +287,87 @@ union content_msg_data {
/* The following are for hlcache */
/**
* Destroy and free a content.
*
* Calls the destroy function for the content, and frees the structure.
*/
void content_destroy(struct content *c);
/**
* Register a user for callbacks.
*
* \param c the content to register
* \param callback the user callback function
* \param pw callback private data
* \return true on success, false otherwise on memory exhaustion
*
* The callback will be called when content_broadcast() is
* called with the content.
*/
bool content_add_user(struct content *h,
void (*callback)(
struct content *c,
content_msg msg,
const union content_msg_data *data,
void *pw),
void *pw);
bool content_add_user(
struct content *h,
void (*callback)(
struct content *c,
content_msg msg,
const union content_msg_data *data,
void *pw),
void *pw);
void content_remove_user(
struct content *c,
void (*callback)(
struct content *c,
content_msg msg,
const union content_msg_data *data,
void *pw),
void *pw);
/**
* Remove a callback user.
*
* The callback function and pw must be identical to those passed to
* content_add_user().
*
* \param c Content to remove user from
* \param callback passed when added
* \param ctx Context passed when added
*/
void content_remove_user(struct content *c,
void (*callback)(
struct content *c,
content_msg msg,
const union content_msg_data *data,
void *pw),
void *ctx);
/**
* Count users for the content.
*
* \param c Content to consider
*/
uint32_t content_count_users(struct content *c);
/**
* Determine if quirks mode matches
*
* \param c Content to consider
* \param quirks Quirks mode to match
* \return True if quirks match, false otherwise
*/
bool content_matches_quirks(struct content *c, bool quirks);
/**
* Determine if a content is shareable
*
* \param c Content to consider
* \return True if content is shareable, false otherwise
*/
bool content_is_shareable(struct content *c);
/* only used by cocoa apple image handling and for getting nsurl of content */
/**
* Retrieve the low-level cache handle for a content
*
* \note only used by hlcache
*
* \param c Content to retrieve from
* \return Low-level cache handle
*/
const struct llcache_handle *content_get_llcache_handle(struct content *c);
/**
* Retrieve URL associated with content
*
@ -330,35 +376,123 @@ const struct llcache_handle *content_get_llcache_handle(struct content *c);
*/
struct nsurl *content_get_url(struct content *c);
/**
* Clone a content object in its current state.
*
* \param c Content to clone
* \return Clone of \a c
*/
struct content *content_clone(struct content *c);
/**
* Abort a content object
*
* \param c The content object to abort
* \return NSERROR_OK on success, otherwise appropriate error
*/
nserror content_abort(struct content *c);
/* Client functions */
/**
* Get whether a content can reformat
*
* \param h content to check
* \return whether the content can reformat
*/
bool content_can_reformat(struct hlcache_handle *h);
/**
* Reformat to new size.
*
* Calls the reformat function for the content.
*/
void content_reformat(struct hlcache_handle *h, bool background,
int width, int height);
/**
* Request a redraw of an area of a content
*
* \param h high-level cache handle
* \param x x co-ord of left edge
* \param y y co-ord of top edge
* \param width Width of rectangle
* \param height Height of rectangle
*/
void content_request_redraw(struct hlcache_handle *h,
int x, int y, int width, int height);
/**
* Handle mouse movements in a content window.
*
* \param h Content handle
* \param bw browser window
* \param mouse state of mouse buttons and modifier keys
* \param x coordinate of mouse
* \param y coordinate of mouse
*/
void content_mouse_track(struct hlcache_handle *h, struct browser_window *bw,
browser_mouse_state mouse, int x, int y);
/**
* Handle mouse clicks and movements in a content window.
*
* \param h Content handle
* \param bw browser window
* \param mouse state of mouse buttons and modifier keys
* \param x coordinate of mouse
* \param y coordinate of mouse
*
* This function handles both hovering and clicking. It is important that the
* code path is identical (except that hovering doesn't carry out the action),
* so that the status bar reflects exactly what will happen. Having separate
* code paths opens the possibility that an attacker will make the status bar
* show some harmless action where clicking will be harmful.
*/
void content_mouse_action(struct hlcache_handle *h, struct browser_window *bw,
browser_mouse_state mouse, int x, int y);
/**
* Handle keypresses.
*
* \param h Content handle
* \param key The UCS4 character codepoint
* \return true if key handled, false otherwise
*/
bool content_keypress(struct hlcache_handle *h, uint32_t key);
/**
* A window containing the content has been opened.
*
* \param h handle to content that has been opened
* \param bw browser window containing the content
* \param page content of type CONTENT_HTML containing h, or NULL if not an
* object within a page
* \param params object parameters, or NULL if not an object
*
* Calls the open function for the content.
*/
nserror content_open(struct hlcache_handle *h, struct browser_window *bw,
struct content *page, struct object_params *params);
/**
* The window containing the content has been closed.
*
* Calls the close function for the content.
*/
nserror content_close(struct hlcache_handle *h);
/**
* Tell a content that any selection it has, or one of its objects
* has, must be cleared.
*/
void content_clear_selection(struct hlcache_handle *h);
/**
* Get a text selection from a content. Ownership is passed to the caller,
* who must free() it.
*/
char * content_get_selection(struct hlcache_handle *h);
/**
@ -372,15 +506,39 @@ char * content_get_selection(struct hlcache_handle *h);
nserror content_get_contextual_content(struct hlcache_handle *h,
int x, int y, struct browser_window_features *data);
/**
* scroll content at coordnate
*
* \param[in] h Handle to content to examine.
* \param[in] x The x coordinate to examine.
* \param[in] y The y coordinate to examine.
*/
bool content_scroll_at_point(struct hlcache_handle *h,
int x, int y, int scrx, int scry);
/**
* Drag and drop a file at coordinate
*
* \param[in] h Handle to content to examine.
* \param[in] x The x coordinate to examine.
* \param[in] y The y coordinate to examine.
*/
bool content_drop_file_at_point(struct hlcache_handle *h,
int x, int y, char *file);
/**
* Search a content
*
* \param[in] h Handle to content to search.
*/
void content_search(struct hlcache_handle *h, void *context,
search_flags_t flags, const char *string);
/**
* Clear a search
*
* \param[in] h Handle to content to clear search from.
*/
void content_search_clear(struct hlcache_handle *h);

245
content/content_protected.h
View File

@ -24,18 +24,25 @@
* The content functions manipulate struct contents, which correspond to URLs.
*/
#ifndef _NETSURF_CONTENT_CONTENT_PROTECTED_H_
#define _NETSURF_CONTENT_CONTENT_PROTECTED_H_
#ifndef NETSURF_CONTENT_CONTENT_PROTECTED_H_
#define NETSURF_CONTENT_CONTENT_PROTECTED_H_
#include <stdio.h>
#include "utils/nsurl.h"
#include "netsurf/content_type.h"
#include "content/content.h"
struct nsurl;
struct content_redraw_data;
struct http_parameter;
struct llcache_handle;
struct object_params;
/**
* Content operation function table
*
* function table implementing a content type.
*/
struct content_handler {
void (*fini)(void);
@ -46,7 +53,7 @@ struct content_handler {
const char *fallback_charset, bool quirks,
struct content **c);
bool (*process_data)(struct content *c,
bool (*process_data)(struct content *c,
const char *data, unsigned int size);
bool (*data_complete)(struct content *c);
void (*reformat)(struct content *c, int width, int height);
@ -85,14 +92,20 @@ struct content_handler {
bool (*exec)(struct content *c, const char *src, size_t srclen);
bool (*saw_insecure_objects)(struct content *c);
/** handler dependant content sensitive internal data interface. */
/**
* handler dependant content sensitive internal data interface.
*/
void * (*get_internal)(const struct content *c, void *context);
/** There must be one content per user for this type. */
/**
* There must be one content per user for this type.
*/
bool no_share;
};
/** Linked list of users of a content. */
/**
* Linked list of users of a content.
*/
struct content_user
{
void (*callback)(
@ -105,68 +118,180 @@ struct content_user
struct content_user *next;
};
/** Corresponds to a single URL. */
/**
* Content which corresponds to a single URL.
*/
struct content {
struct llcache_handle *llcache; /**< Low-level cache object */
/**
* Low-level cache object
*/
struct llcache_handle *llcache;
lwc_string *mime_type; /**< Original MIME type of data */
/**
* Original MIME type of data
*/
lwc_string *mime_type;
const struct content_handler *handler; /**< Handler for content */
/**
* Handler for content
*/
const struct content_handler *handler;
content_status status; /**< Current status. */
/**
* Current status.
*/
content_status status;
int width, height; /**< Dimensions, if applicable. */
int available_width; /**< Viewport width. */
int available_height; /**< Viewport height. */
/**
* Width dimension, if applicable.
*/
int width;
/**
* Height dimension, if applicable.
*/
int height;
/**
* Viewport width.
*/
int available_width;
/**
* Viewport height.
*/
int available_height;
bool quirks; /**< Content is in quirks mode */
char *fallback_charset; /**< Fallback charset, or NULL */
/**
* Content is in quirks mode
*/
bool quirks;
/**
* Fallback charset, or NULL
*/
char *fallback_charset;
nsurl *refresh; /**< URL for refresh request */
/**
* URL for refresh request
*/
struct nsurl *refresh;
struct content_rfc5988_link *links; /**< list of metadata links */
/**
* list of metadata links
*/
struct content_rfc5988_link *links;
/** Creation timestamp when LOADING or READY.
* Total time in ms when DONE.
/**
* Creation timestamp when LOADING or READY. Total time in ms
* when DONE.
*/
uint64_t time;
uint64_t reformat_time; /**< Earliest time to attempt a period
* reflow while fetching a page's objects.
*/
/**
* Earliest time to attempt a period reflow while fetching a
* page's objects.
*/
uint64_t reformat_time;
unsigned int size; /**< Estimated size of all data
associated with this content */
char *title; /**< Title for browser window. */
unsigned int active; /**< Number of child fetches or
conversions currently in progress. */
struct content_user *user_list; /**< List of users. */
char status_message[120]; /**< Full text for status bar. */
char sub_status[80]; /**< Status of content. */
/** Content is being processed: data structures may be inconsistent
* and content must not be redrawn or modified. */
/**
* Estimated size of all data associated with this content
*/
unsigned int size;
/**
* Title for browser window.
*/
char *title;
/**
* Number of child fetches or conversions currently in progress.
*/
unsigned int active;
/**
* List of users.
*/
struct content_user *user_list;
/**
* Full text for status bar.
*/
char status_message[120];
/**
* Status of content.
*/
char sub_status[80];
/**
* Content is being processed: data structures may be
* inconsistent and content must not be redrawn or modified.
*/
bool locked;
unsigned long total_size; /**< Total data size, 0 if unknown. */
long http_code; /**< HTTP status code, 0 if not HTTP. */
/**
* Total data size, 0 if unknown.
*/
unsigned long total_size;
/**
* HTTP status code, 0 if not HTTP.
*/
long http_code;
};
extern const char * const content_type_name[];
extern const char * const content_status_name[];
/**
* Initialise a new base content structure.
*
* \param c Content to initialise
* \param handler Content handler
* \param imime_type MIME type of content
* \param params HTTP parameters
* \param llcache Source data handle
* \param fallback_charset Fallback charset
* \param quirks Quirkiness of content
* \return NSERROR_OK on success, appropriate error otherwise
*/
nserror content__init(struct content *c, const struct content_handler *handler,
lwc_string *imime_type, const struct http_parameter *params,
struct llcache_handle *llcache, const char *fallback_charset,
bool quirks);
/**
* Clone a content's data members
*
* \param c Content to clone
* \param nc Content to populate
* \return NSERROR_OK on success, appropriate error otherwise
*/
nserror content__clone(const struct content *c, struct content *nc);
/**
* Put a content in status CONTENT_STATUS_READY and unlock the content.
*/
void content_set_ready(struct content *c);
/**
* Put a content in status CONTENT_STATUS_DONE.
*/
void content_set_done(struct content *c);
/**
* Put a content in status CONTENT_STATUS_ERROR and unlock the content.
*
* \note We expect the caller to broadcast an error report if needed.
*/
void content_set_error(struct content *c);
/**
* Updates content with new status.
*
* The textual status contained in the content is updated with given string.
*
* \param c The content to set status in.
* \param status_message new textual status
*/
void content_set_status(struct content *c, const char *status_message);
void content_broadcast(struct content *c, content_msg msg,
const union content_msg_data *data);
/**
* Send a message to all users.
*/
void content_broadcast(struct content *c, content_msg msg, const union content_msg_data *data);
/**
* Send an error message to all users.
*
@ -176,16 +301,42 @@ void content_broadcast(struct content *c, content_msg msg,
*/
void content_broadcast_error(struct content *c, nserror errorcode, const char *msg);
bool content__add_rfc5988_link(struct content *c,
const struct content_rfc5988_link *link);
struct content_rfc5988_link *content__free_rfc5988_link(
struct content_rfc5988_link *link);
/**
* associate a metadata link with a content.
*
* \param c content to add link to
* \param link The rfc5988 link to add
*/
bool content__add_rfc5988_link(struct content *c, const struct content_rfc5988_link *link);
void content__reformat(struct content *c, bool background,
int width, int height);
void content__request_redraw(struct content *c,
int x, int y, int width, int height);
/**
* free a rfc5988 link
*
* \param link The link to free
* \return The next link in the chain
*/
struct content_rfc5988_link *content__free_rfc5988_link(struct content_rfc5988_link *link);
/**
* cause a content to be reformatted.
*
* \param c content to be reformatted
* \param background perform reformat in background
* \param width The available width to reformat content in
* \param height The available height to reformat content in
*/
void content__reformat(struct content *c, bool background, int width, int height);
/**
* Request a redraw of an area of a content
*
* \param c Content
* \param x x co-ord of left edge
* \param y y co-ord of top edge
* \param width Width of rectangle
* \param height Height of rectangle
*/
void content__request_redraw(struct content *c, int x, int y, int width, int height);
/**
* Retrieve mime-type of content
@ -270,7 +421,7 @@ void content__invalidate_reuse_data(struct content *c);
* \param c Content to retrieve refresh URL from
* \return Pointer to URL or NULL if none
*/
nsurl *content__get_refresh_url(struct content *c);
struct nsurl *content__get_refresh_url(struct content *c);
/**
* Retrieve the bitmap contained in an image content

3
content/handlers/html/box_construct.c
View File

@ -33,6 +33,7 @@
#include "utils/talloc.h"
#include "utils/string.h"
#include "utils/ascii.h"
#include "utils/nsurl.h"
#include "netsurf/misc.h"
#include "css/select.h"
#include "desktop/gui_internal.h"
@ -68,7 +69,7 @@ struct box_construct_props {
/** Style from which to inherit, or NULL if none */
const css_computed_style *parent_style;
/** Current link target, or NULL if none */
nsurl *href;
struct nsurl *href;
/** Current frame target, or NULL if none */
const char *target;
/** Current title attribute, or NULL if none */

1
content/handlers/html/box_manipulate.c
View File

@ -28,6 +28,7 @@
#include "utils/errors.h"
#include "utils/talloc.h"
#include "utils/nsurl.h"
#include "netsurf/types.h"
#include "netsurf/mouse.h"
#include "desktop/scrollbar.h"

1
content/handlers/html/box_special.c
View File

@ -36,6 +36,7 @@
#include "utils/talloc.h"
#include "utils/string.h"
#include "utils/ascii.h"
#include "utils/nsurl.h"
#include "netsurf/plot_style.h"
#include "css/hints.h"
#include "desktop/frame_types.h"

1
content/handlers/html/dom_event.c
View File

@ -27,6 +27,7 @@
#include "utils/log.h"
#include "utils/ascii.h"
#include "utils/string.h"
#include "utils/nsurl.h"
#include "javascript/js.h"
#include "html/private.h"

1
content/handlers/html/layout.c
View File

@ -47,6 +47,7 @@
#include "utils/talloc.h"
#include "utils/utils.h"
#include "utils/nsoption.h"
#include "utils/nsurl.h"
#include "netsurf/inttypes.h"
#include "netsurf/content.h"
#include "netsurf/browser_window.h"

3
content/handlers/html/object.h
View File

@ -27,6 +27,7 @@
struct html_content;
struct browser_window;
struct box;
struct nsurl;
/**
* Start a fetch for an object required by a page.
@ -42,7 +43,7 @@ struct box;
* \param background this is a background image
* \return true on success, false on memory exhaustion
*/
bool html_fetch_object(struct html_content *c, nsurl *url, struct box *box, content_type permitted_types, bool background);
bool html_fetch_object(struct html_content *c, struct nsurl *url, struct box *box, content_type permitted_types, bool background);
/**
* release memory of content objects associated with a HTML content

4
content/handlers/html/private.h
View File

@ -107,7 +107,7 @@ typedef struct html_content {
dom_hubbub_encoding_source encoding_source;
/** Base URL (may be a copy of content->url). */
nsurl *base_url;
struct nsurl *base_url;
/** Base target */
char *base_target;
@ -341,7 +341,7 @@ struct form_control *html_forms_get_control_for_node(struct form *forms,
* \return NSERROR_OK on successful registration or error code on failure.
*/
nserror html_css_fetcher_register(void);
nserror html_css_fetcher_add_item(dom_string *data, nsurl *base_url,
nserror html_css_fetcher_add_item(dom_string *data, struct nsurl *base_url,
uint32_t *key);

1
content/handlers/image/svg.c
View File

@ -30,6 +30,7 @@
#include "utils/messages.h"
#include "utils/utils.h"
#include "utils/nsurl.h"
#include "netsurf/plotters.h"
#include "netsurf/content.h"
#include "content/content_protected.h"