[[!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"]]