diff options
author | Daniel Silverstone <dsilvers@digital-scurf.org> | 2017-02-04 09:41:13 +0000 |
---|---|---|
committer | Daniel Silverstone <dsilvers@digital-scurf.org> | 2017-02-04 09:41:13 +0000 |
commit | e7366bf41f68cfe07e9ea03fc4a398baecbae651 (patch) | |
tree | 5bb9c3cbe7eab7e70ff1ebd65d9de59a694762df /documentation/contents.mdwn | |
download | netsurf-wiki-e7366bf41f68cfe07e9ea03fc4a398baecbae651.tar.gz netsurf-wiki-e7366bf41f68cfe07e9ea03fc4a398baecbae651.tar.bz2 |
Initial conversion from MediaWiki, 20170204
Diffstat (limited to 'documentation/contents.mdwn')
-rw-r--r-- | documentation/contents.mdwn | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/documentation/contents.mdwn b/documentation/contents.mdwn new file mode 100644 index 0000000..dea18da --- /dev/null +++ b/documentation/contents.mdwn @@ -0,0 +1,148 @@ +[[!meta title="Documentation/Contents"]] +[[!meta author="James Bursa"]] +[[!meta date="2010-03-01T02:56:11Z"]] + + +[[!toc]] The modules in the content +directory provide the infrastructure for fetching data, managing it in +memory, and converting it for display. + +Contents +-------- + +The data related to each URL used by NetSurf is stored in a 'struct +content' (known as a "content"). A content contains + +- a 'content type' which corresponds to the MIME type of the URL (for + example CONTENT\_HTML, CONTENT\_JPEG, or CONTENT\_OTHER) +- a status (for example LOADING, DONE, or ERROR) +- type independent data such as the URL and raw source bytes +- a union of structs for type dependent data (for example 'struct + content\_html\_data') + +Contents are stored in a global linked list 'content\_list', also known +as the "memory cache". + +The content\_\* functions provide a general interface for handling these +structures. They use a table of handlers to call type-specific code +('handler\_map'). For example, content\_redraw() may call html\_redraw() +or nsjpeg\_redraw() depending on the type of content. + +Each content has a list of users. A user is a callback function which is +sent a message (called) when something interesting happens to the +content (for example, it's ready to be displayed). Examples of users are +browser windows (of HTML contents) and HTML contents (of JPEG contents). + +Some content types may not be shared among users: an HTML content is +dependent on the width of the window, so sharing by two or more windows +wouldn't work. Thus there may be more than one content with the same URL +in memory. + +Content status +-------------- + +The status of a content follows a fixed order. Certain content functions +change the status, and each change of status results in a message to all +users of the content: + +- content\_create() creates a content in status TYPE\_UNKNOWN +- content\_set\_type() takes a content TYPE\_UNKNOWN to one of + - LOADING (sends optional MSG\_NEWPTR followed by MSG\_LOADING) + - ERROR (sends MSG\_ERROR) +- content\_process\_data() takes LOADING to one of + - LOADING (no message) + - ERROR (MSG\_ERROR) +- content\_convert() takes LOADING to one of + - READY (MSG\_READY) + - DONE (MSG\_READY, MSG\_DONE) + - ERROR (MSG\_ERROR) +- a content can move from READY to DONE by itself, for example HTML + contents become DONE when all images are fetched and the document is + reformatted (MSG\_DONE) +- content\_stop() aborts loading of a READY content and results in + status DONE (MSG\_DONE) + +Type functions +-------------- + +The type-specific functions for a content are as follows (where 'type' +is replaced by something): + +- type\_create():: called to initialise type-specific fields in the + content structure. Optional. +- type\_process\_data():: called when some data arrives. Optional. +- type\_convert():: called when data has finished arriving. The + content needs to be converted for display. Must set the status to + one of CONTENT\_STATUS\_READY or CONTENT\_STATUS\_DONE if no error + occurs. Optional, but probably required for non-trivial types. +- type\_reformat():: called when, for example, the window has been + resized, and the content needs reformatting for the new size. + Optional. +- type\_destroy():: called when the content is being destroyed. Free + all resources. Optional. +- type\_redraw():: called to plot the content to screen. +- type\_redraw\_tiled():: called to plot the content tiled across the + screen. Optional. +- type\_stop(): called when the user interrupts in status + CONTENT\_STATUS\_READY. Must stop any processing and set the status + to CONTENT\_STATUS\_DONE. Required iff the status can be + CONTENT\_STATUS\_READY. +- type\_open(): called when a window containing the content is opened. + Probably only makes sense if no\_share is set for the content type + in handler\_map. Optional. +- type\_close():: called when the window containing the content is + closed. Optional. + +If an error occurs in type\_create(), type\_process\_data(), +type\_convert(), CONTENT\_MSG\_ERROR must be broadcast and false +returned. The \_destroy function will be called soon after. + +Memory allocation +----------------- + +Each content structure is allocated using talloc, and all data related +to a content should be allocated as a child block of the content +structure using talloc. This will ensure that all memory used by a +content is freed. + +Contents must keep an estimate of non-talloc allocations in the +total\_size attribute. This is used to control the size of the memory +cache. + +Creating and fetching contents +------------------------------ + +A high-level interface to starting the process of fetching and +converting an URL is provided by the fetchcache functions, which check +the memory cache for a url and fetch, convert, and cache it if not +present. + +The fetch module provides a low-level URL fetching interface. + +Adding support for a new content type +------------------------------------- + +Addition of support for new content types is fairly simple and the +process is as follows: + +- Implement, or at least stub out, the new content type handler. See + the 'Type Functions' section above for details of the type handler + API. +- Add a type value to the 'content\_type' enumeration + (content\_type.h) +- Add an entry for the new type's private data in the 'data' union + within 'struct content' (content.h) +- Add appropriate mappings in the 'mime\_map' table from MIME type + strings to the 'content\_type' value created. (content.c) +- Add a textual name for the new content type to + 'content\_type\_name'. This array is indexed by 'content\_type'. + (content.c) +- Add an entry for the new content type's handler in the + 'handler\_map' array. This array is indexed by 'content\_type'. + (content.c) + +For examples of content type handlers, consult the image/ directory. The +JPEG handler is fairly self-explanatory. + +[[!inline raw=yes pages="Documentation"]] + |