1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
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"]]
|
