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"]]
+