Diffstat (limited to 'documentation/contents.mdwn')
1 files changed, 148 insertions, 0 deletions
diff --git a/documentation/contents.mdwn b/documentation/contents.mdwn
new file mode 100644
@@ -0,0 +1,148 @@
+[[!meta author="James Bursa"]]
+[[!toc]] The modules in the content
+directory provide the infrastructure for fetching data, managing it in
+memory, and converting it for display.
+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
+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
+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)
+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.
+- 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
+- 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.
+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
+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
+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
+- Add a type value to the 'content\_type' enumeration
+- 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'.
+- Add an entry for the new content type's handler in the
+ 'handler\_map' array. This array is indexed by 'content\_type'.
+For examples of content type handlers, consult the image/ directory. The
+JPEG handler is fairly self-explanatory.
+[[!inline raw=yes pages="Documentation"]]