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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
|
<HTML>
<HEAD>
<TITLE>HTFormat: The format manager in the WWW Library</TITLE>
<NEXTID N="z18">
</HEAD>
<BODY>
<H1>Manage different document formats</H1>Here we describe the functions of
the HTFormat module which handles conversion between different data
representations. (In MIME parlance, a representation is known as a content-
type. In WWW the term "format" is often used as it is shorter).<P>
This module is implemented by <A NAME="z0" HREF="HTFormat.c">HTFormat.c</A>.
The module is a part of the <A NAME="z10" HREF="Overview.html">WWW library</A>.
<H2>Preamble</H2>
<PRE>#ifndef HTFORMAT_H
#define HTFORMAT_H
#include "HTUtils.h"
#include <A
NAME="z7" HREF="HTStream.html">"HTStream.h"</A>
#include "HTAtom.h"
#include "HTList.h"
#ifdef SHORT_NAMES
#define HTOutputSource HTOuSour
#define HTOutputBinary HTOuBina
#endif
typedef struct _HTContentDescription {
char * filename;
HTAtom * content_type;
HTAtom * content_language;
HTAtom * content_encoding;
int content_length;
float quality;
} HTContentDescription;
PUBLIC void HTAcceptEncoding PARAMS((HTList * list,
char * enc,
float quality));
PUBLIC void HTAcceptLanguage PARAMS((HTList * list,
char * lang,
float quality));
PUBLIC BOOL HTRank PARAMS((HTList * possibilities,
HTList * accepted_content_types,
HTList * accepted_content_languages,
HTList * accepted_content_encodings));
</PRE>
<H2>HT<A
NAME="z15"> Input Socket: Buffering for network
in</A></H2>This routines provide simple character
input from sockets. These are used
for parsing input in arbitrary IP
protocols (Gopher, NNTP, FTP).
<PRE>#define INPUT_BUFFER_SIZE 4096 /* Tradeoff spped vs memory*/
typedef struct _socket_buffer {
char input_buffer[INPUT_BUFFER_SIZE];
char * input_pointer;
char * input_limit;
int input_file_number;
BOOL s_do_buffering;
char * s_buffer;
int s_buffer_size;
char * s_buffer_cur;
} HTInputSocket;
</PRE>
<H3>Create input buffer and set file
number</H3>
<PRE>extern HTInputSocket* HTInputSocket_new PARAMS((int file_number));
</PRE>
<H3>Get next character from buffer</H3>
<PRE>extern int HTInputSocket_getCharacter PARAMS((HTInputSocket* isoc));
</PRE>
<H3>Read block from input socket</H3>Read *len characters and return a
buffer (don't free) containing *len
characters ( *len may have changed).
Buffer is not NULL-terminated.
<PRE>extern char * HTInputSocket_getBlock PARAMS((HTInputSocket * isoc,
int * len));
</PRE>
<H3>Free input socket buffer</H3>
<PRE>extern void HTInputSocket_free PARAMS((HTInputSocket * isoc));
PUBLIC char * HTInputSocket_getLine PARAMS((HTInputSocket * isoc));
PUBLIC char * HTInputSocket_getUnfoldedLine PARAMS((HTInputSocket * isoc));
PUBLIC char * HTInputSocket_getStatusLine PARAMS((HTInputSocket * isoc));
PUBLIC BOOL HTInputSocket_seemsBinary PARAMS((HTInputSocket * isoc));
</PRE>
<H3>Security Buffering</H3>
When it's necessary to get e.g. the header section, or part of it,
exactly as it came from the client to calculate the message digest,
these functions turn buffering on and off. All the material returned
by <CODE>HTInputSocket_getStatusLine()</CODE>,
<CODE>HTInputSocket_getUnfoldedLine()</CODE> and
<CODE>HTInputSocket_getLine()</CODE> gets buffered after a call to
<CODE>HTInputSocket_startBuffering()</CODE> until either
<CODE>HTInputSocket_stopBuffering()</CODE> is called, or an empty line is
returned by any of these functions (end of body section).
<CODE>HTInputSocket_getBuffer()</CODE> returns the number of
characters buffered, and sets the given buffer pointer to point to
internal buffer. This buffer exists until <CODE>HTInputSocket</CODE>
object is freed.
<PRE>
PUBLIC void HTInputSocket_startBuffering PARAMS((HTInputSocket * isoc));
PUBLIC void HTInputSocket_stopBuffering PARAMS((HTInputSocket * isoc));
PUBLIC int HTInputSocket_getBuffer PARAMS((HTInputSocket * isoc,
char ** buffer_ptr));
</PRE>
<H2>The HTFormat type</H2>We use the HTAtom object for holding
representations. This allows faster
manipulation (comparison and copying)
that if we stayed with strings.<P>
The following have to be defined
in advance of the other include files
because of circular references.
<PRE>typedef HTAtom * HTFormat;
#include <A
NAME="z14" HREF="HTAccess.html">"HTAccess.h"</A> /* Required for HTRequest definition */
</PRE>
These macros (which used to be constants) define some basic internally
referenced representations.
<H3>Internal ones</H3>
The www/xxx ones are of course not MIME standard.<P>
star/star is an output format which leaves the input untouched. It is
useful for diagnostics, and for users who want to see the original,
whatever it is.
<PRE>
#define WWW_SOURCE HTAtom_for("*/*") /* Whatever it was originally */
</PRE>
www/present represents the user's perception of the document. If you
convert to www/present, you present the material to the user.
<PRE>
#define WWW_PRESENT HTAtom_for("www/present") /* The user's perception */
</PRE>
The message/rfc822 format means a MIME message or a plain text message
with no MIME header. This is what is returned by an HTTP server.
<PRE>
#define WWW_MIME HTAtom_for("www/mime") /* A MIME message */
</PRE>
www/print is like www/present except it represents a printed copy.
<PRE>
#define WWW_PRINT HTAtom_for("www/print") /* A printed copy */
</PRE>
www/unknown is a really unknown type. Some default action is
appropriate.
<PRE>
#define WWW_UNKNOWN HTAtom_for("www/unknown")
</PRE>
<H3>MIME ones (a few)</H3>
These are regular MIME types. HTML is assumed to be added by the W3
code. application/octet-stream was mistakenly application/binary in
earlier libwww versions (pre 2.11).
<PRE>
#define WWW_PLAINTEXT HTAtom_for("text/plain")
#define WWW_POSTSCRIPT HTAtom_for("application/postscript")
#define WWW_RICHTEXT HTAtom_for("application/rtf")
#define WWW_AUDIO HTAtom_for("audio/basic")
#define WWW_HTML HTAtom_for("text/html")
#define WWW_BINARY HTAtom_for("application/octet-stream")
#define WWW_VIDEO HTAtom_for("video/mpeg")
</PRE>
Extra types used in the library
<PRE>
#define WWW_NEWSLIST HTAtom_for("text/newslist")
</PRE>
We must include the following file after defining HTFormat, to which
it makes reference.
<H2>The HTEncoding type</H2>
<PRE>typedef HTAtom* HTEncoding;
</PRE>The following are values for the
MIME types:
<PRE>#define WWW_ENC_7BIT HTAtom_for("7bit")
#define WWW_ENC_8BIT HTAtom_for("8bit")
#define WWW_ENC_BINARY HTAtom_for("binary")
</PRE>We also add
<PRE>#define WWW_ENC_COMPRESS HTAtom_for("compress")
#include "HTAnchor.h"
</PRE>
<H2>The HTPresentation and HTConverter types</H2>
This HTPresentation structure represents a possible conversion
algorithm from one format to annother. It includes a pointer to a
conversion routine. The conversion routine returns a stream to which
data should be fed. See also <A NAME="z5"
HREF="#z3">HTStreamStack</A> which scans the list of registered
converters and calls one. See the <A NAME="z6"
HREF="HTInit.html">initialisation module</A> for a list of conversion
routines.
<PRE>
typedef struct _HTPresentation HTPresentation;
typedef HTStream * <A NAME="z12">HTConverter</A> PARAMS((
HTRequest * request,
void * param,
HTFormat input_format,
HTFormat output_format,
HTStream * output_stream));
struct _HTPresentation {
HTAtom* rep; /* representation name atomized */
HTAtom* rep_out; /* resulting representation */
HTConverter *converter; /* The routine to gen the stream stack */
char * command; /* MIME-format string */
float quality; /* Between 0 (bad) and 1 (good) */
float secs;
float secs_per_byte;
};
</PRE>
A global list of converters is kept by this module. It is also
scanned by modules which want to know the set of formats supported.
for example. Note there is also an additional list associated with
each <A NAME="z16" HREF="HTAccess.html#z5">request</A>.
<PRE>extern HTList * <A
NAME="z17">HTConversions</A> ;
</PRE>
<H2>HTSetPresentation: Register a system
command to present a format</H2>
<H3>On entry,</H3>
<DL>
<DT>rep
<DD> is the MIME - style format name
<DT>command
<DD> is the MAILCAP - style command
template
<DT>quality
<DD> A degradation faction 0..1
<DT>maxbytes
<DD> A limit on the length acceptable
as input (0 infinite)
<DT>maxsecs
<DD> A limit on the time user
will wait (0 for infinity)
</DL>
<PRE>extern void HTSetPresentation PARAMS((
HTList * conversions,
CONST char * representation,
CONST char * command,
float quality,
float secs,
float secs_per_byte
));
</PRE>
<H2>HTSetConversion: Register a converstion
routine</H2>
<H3>On entry,</H3>
<DL>
<DT>rep_in
<DD> is the content-type input
<DT>rep_out
<DD> is the resulting content-type
<DT>converter
<DD> is the routine to make
the stream to do it
</DL>
<PRE>
extern void HTSetConversion PARAMS((
HTList * conversions,
CONST char * rep_in,
CONST char * rep_out,
HTConverter * converter,
float quality,
float secs,
float secs_per_byte
));
</PRE>
<H2><A
NAME="z3">HTStreamStack: Create a stack of
streams</A></H2>This is the routine which actually
sets up the conversion. It currently
checks only for direct conversions,
but multi-stage conversions are forseen.
It takes a stream into which the
output should be sent in the final
format, builds the conversion stack,
and returns a stream into which the
data in the input format should be
fed. The anchor is passed because
hypertxet objects load information
into the anchor object which represents
them. <P>
If <CODE>guess</CODE> is true and input format is
<CODE>www/unknown</CODE>, try to guess the format
by looking at the first few butes of the stream. <P>
<PRE>extern HTStream * HTStreamStack PARAMS((
HTFormat format_in,
HTRequest * request,
BOOL guess));
</PRE>
<H2>HTStackValue: Find the cost of a
filter stack</H2>Must return the cost of the same
stack which HTStreamStack would set
up.
<H3>On entry,</H3>
<DL>
<DT>format_in
<DD> The fomat of the data to
be converted
<DT>format_out
<DD> The format required
<DT>initial_value
<DD> The intrinsic "value"
of the data before conversion on
a scale from 0 to 1
<DT>length
<DD> The number of bytes expected
in the input format
</DL>
<PRE>extern float HTStackValue PARAMS((
HTList * conversions,
HTFormat format_in,
HTFormat format_out,
float initial_value,
long int length));
#define NO_VALUE_FOUND -1e20 /* returned if none found */
</PRE>
<H2><A
NAME="z1">HTCopy: Copy a socket to a stream</A></H2>This is used by the protocol engines
to send data down a stream, typically
one which has been generated by HTStreamStack.
Returns the number of bytes transferred.
<PRE>extern int HTCopy PARAMS((
int file_number,
HTStream* sink));
</PRE>
<H2><A
NAME="c6">HTFileCopy: Copy a file to a stream</A></H2>This is used by the protocol engines
to send data down a stream, typically
one which has been generated by HTStreamStack.
It is currently called by <A
NAME="z9" HREF="#c7">HTParseFile</A>
<PRE>extern void HTFileCopy PARAMS((
FILE* fp,
HTStream* sink));
</PRE>
<H2><A
NAME="c2">HTCopyNoCR: Copy a socket to a stream,
stripping CR characters.</A></H2>It is slower than <A
NAME="z2" HREF="#z1">HTCopy</A> .
<PRE>
extern void HTCopyNoCR PARAMS((
int file_number,
HTStream* sink));
</PRE>
<H2>HTParseSocket: Parse a socket given
its format</H2>This routine is called by protocol
modules to load an object. uses<A
NAME="z4" HREF="#z3">
HTStreamStack</A> and the copy routines
above. Returns HT_LOADED if succesful,
<0 if not.
<PRE>extern int HTParseSocket PARAMS((
HTFormat format_in,
int file_number,
HTRequest * request));
</PRE>
<H2><A
NAME="c1">HTParseFile: Parse a File through
a file pointer</A></H2>This routine is called by protocols
modules to load an object. uses<A
NAME="z4" HREF="#z3"> HTStreamStack</A>
and <A
NAME="c7" HREF="#c6">HTFileCopy</A> . Returns HT_LOADED
if succesful, <0 if not.
<PRE>extern int HTParseFile PARAMS((
HTFormat format_in,
FILE *fp,
HTRequest * request));
</PRE>
<H2><A
NAME="z11">HTNetToText: Convert Net ASCII to
local representation</A></H2>This is a filter stream suitable
for taking text from a socket and
passing it into a stream which expects
text in the local C representation.
It does ASCII and newline conversion.
As usual, pass its output stream
to it when creating it.
<PRE>extern HTStream * HTNetToText PARAMS ((HTStream * sink));
</PRE>
<H2>HTFormatInit: Set up default presentations
and conversions</H2>These are defined in HTInit.c or
HTSInit.c if these have been replaced.
If you don't call this routine, and
you don't define any presentations,
then this routine will automatically
be called the first time a conversion
is needed. However, if you explicitly
add some conversions (eg using HTLoadRules)
then you may want also to explicitly
call this to get the defaults as
well.
<PRE>
extern void HTFormatInit PARAMS((HTList * conversions));
</PRE>
<H2>HTFormatInitNIM: Set up default presentations
and conversions</H2>This is a slightly different version
of HTFormatInit, but without any
conversions that might use third
party programs. This is intended
for Non Interactive Mode.
<PRE>extern void HTFormatInitNIM PARAMS((HTList * conversions));
</PRE>
<H2>HTFormatDelete: Remove presentations
and conversions</H2>Deletes the list from HTFormatInit
or HTFormatInitNIM
<PRE>extern void HTFormatDelete PARAMS((HTList * conversions));
</PRE>
<H2>Epilogue</H2>
<PRE>extern BOOL HTOutputSource; /* Flag: shortcut parser */
#endif
</PRE>end</BODY>
</HTML>
|
