Debian Codegraph @

WWW/Library/Implementation/HTFormat.h

raw
1 /*
2 * $LynxId: HTFormat.h,v 1.44 2025/01/06 15:13:11 tom Exp $
3 *
4 * HTFormat: The format manager in the WWW Library
5 * MANAGE DIFFERENT DOCUMENT FORMATS
6 *
7 * Here we describe the functions of the HTFormat module which handles conversion between
8 * different data representations. (In MIME parlance, a representation is known as a
9 * content-type. In WWW the term "format" is often used as it is shorter).
10 *
11 * This module is implemented by HTFormat.c. This hypertext document is used to generate
12 * the HTFormat.h include file. Part of the WWW library.
13 */
14 #ifndef HTFORMAT_H
15 #define HTFORMAT_H
16
17 #include <HTStream.h>
18 #include <HTAtom.h>
19 #include <HTList.h>
20 #include <HTAnchor.h>
21
22 #ifdef USE_SOURCE_CACHE
23 #include <HTChunk.h>
24 #endif
25
26 #ifdef USE_BZLIB
27 #include <bzlib.h>
28 #endif
29
30 #ifdef USE_ZLIB
31 #include <zlib.h>
32 #endif
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 /*
38
39 These macros (which used to be constants) define some basic internally
40 referenced representations. The www/xxx ones are of course not MIME
41 standard.
42
43 www/source is an output format which leaves the input untouched. It is
44 useful for diagnostics, and for users who want to see the original, whatever
45 it is.
46
47 */
48 /* Internal ones */
49 #define STR_SOURCE "www/source"
50 extern HTAtom *WWW_SOURCE; /* calculated once, heavy used */
51
52 /*
53
54 www/present represents the user's perception of the document. If you
55 convert to www/present, you present the material to the user.
56
57 */
58 #define STR_PRESENT "www/present"
59 #define WWW_PRESENT HTAtom_for(STR_PRESENT) /* The user's perception */
60
61 #define WWW_DEBUG HTAtom_for("www/debug")
62 /*
63
64 WWW_DEBUG represents the user's perception of debug information, for example
65 sent as a HTML document in a HTTP redirection message.
66
67 */
68
69 /*
70
71 The message/rfc822 format means a MIME message or a plain text message with
72 no MIME header. This is what is returned by an HTTP server.
73
74 */
75 #define WWW_MIME HTAtom_for("www/mime") /* A MIME message */
76
77 /*
78 For parsing only the header. - kw
79 */
80 #define WWW_MIME_HEAD HTAtom_for("message/x-rfc822-head")
81
82 /*
83
84 www/print is like www/present except it represents a printed copy.
85
86 */
87 #define WWW_PRINT HTAtom_for("www/print") /* A printed copy */
88
89 /*
90
91 www/unknown is a really unknown type. Some default action is appropriate.
92
93 */
94 #define WWW_UNKNOWN HTAtom_for("www/unknown")
95
96 #ifdef DIRED_SUPPORT
97 /*
98 www/dired signals directory edit mode.
99 */
100 #define WWW_DIRED HTAtom_for("www/dired")
101 #endif
102
103 /*
104 * Miscellaneous internal MIME types.
105 */
106 #define STR_DOWNLOAD "www/download"
107 #define WWW_DOWNLOAD HTAtom_for(STR_DOWNLOAD)
108
109 #define STR_DUMP "www/dump"
110 #define WWW_DUMP HTAtom_for(STR_DUMP)
111
112 /*
113
114 These are regular MIME types. HTML is assumed to be added by the W3 code.
115 application/octet-stream was mistakenly application/binary in earlier libwww
116 versions (pre 2.11).
117
118 */
119 #define STR_BINARY "application/octet-stream"
120 #define STR_PLAINTEXT "text/plain"
121 #define STR_HTML "text/html"
122
123 #define WWW_BINARY HTAtom_for(STR_BINARY)
124 #define WWW_PLAINTEXT HTAtom_for(STR_PLAINTEXT)
125 #define WWW_HTML HTAtom_for(STR_HTML)
126
127 #define WWW_POSTSCRIPT HTAtom_for("application/postscript")
128 #define WWW_RICHTEXT HTAtom_for("application/rtf")
129 #define WWW_AUDIO HTAtom_for("audio/basic")
130
131 typedef HTAtom *HTEncoding;
132
133 /*
134 * The following are values for the MIME types:
135 */
136 #define WWW_ENC_7BIT HTAtom_for("7bit")
137 #define WWW_ENC_8BIT HTAtom_for("8bit")
138 #define WWW_ENC_BINARY HTAtom_for("binary")
139
140 /*
141 * We also add
142 */
143 #define WWW_ENC_COMPRESS HTAtom_for("compress")
144
145 /*
146 * Does a string designate a real encoding, or is it just
147 * a "dummy" as for example 7bit, 8bit, and binary?
148 */
149 #define IsUnityEncStr(senc) \
150 ((senc)==NULL || *(senc)=='\0' || !strcmp(senc,"identity") ||\
151 !strcmp(senc,"8bit") || !strcmp(senc,"binary") || !strcmp(senc,"7bit"))
152
153 #define IsUnityEnc(enc) \
154 ((enc)==NULL || (enc)==HTAtom_for("identity") ||\
155 (enc)==WWW_ENC_8BIT || (enc)==WWW_ENC_BINARY || (enc)==WWW_ENC_7BIT)
156
157 /*
158
159 The HTPresentation and HTConverter types
160
161 This HTPresentation structure represents a possible conversion algorithm
162 from one format to another. It includes a pointer to a conversion routine.
163 The conversion routine returns a stream to which data should be fed. See
164 also HTStreamStack which scans the list of registered converters and calls
165 one. See the initialisation module for a list of conversion routines.
166
167 */
168 typedef struct _HTPresentation HTPresentation;
169
170 typedef HTStream *HTConverter (HTPresentation *pres,
171 HTParentAnchor *anchor,
172 HTStream *sink);
173
174 struct _HTPresentation {
175 HTAtom *rep; /* representation name atomized */
176 HTAtom *rep_out; /* resulting representation */
177 HTConverter *converter; /* routine to gen the stream stack */
178 char *command; /* MIME-format command string */
179 char *testcommand; /* MIME-format test string */
180 float quality; /* Between 0 (bad) and 1 (good) */
181 float secs;
182 float secs_per_byte;
183 off_t maxbytes;
184 BOOL get_accept; /* list in "Accept:" for GET */
185 int accept_opt; /* matches against LYAcceptMedia */
186 };
187
188 /*
189
190 The list of presentations is kept by this module. It is also scanned by
191 modules which want to know the set of formats supported. for example.
192
193 */
194 extern HTList *HTPresentations;
195
196 /*
197
198 The default presentation is used when no other is appropriate
199
200 */
201 extern HTPresentation *default_presentation;
202
203 /*
204 * Options used for "Content-Type" string
205 */
206 typedef enum {
207 contentBINARY = 0
208 ,contentTEXT
209 ,contentHTML
210 } ContentType;
211
212 /*
213 * Options used for "Accept:" string
214 */
215 typedef enum {
216 /* make the components powers of two so we can add them */
217 mediaINT = 1 /* internal types predefined in HTInit.c */
218 ,mediaEXT = 2 /* external types predefined in HTInit.c */
219 ,mediaCFG = 4 /* types, e.g., viewers, from lynx.cfg */
220 ,mediaUSR = 8 /* user's mime-types, etc. */
221 ,mediaSYS = 16 /* system's mime-types, etc. */
222 /* these are useful flavors for the options menu */
223 ,mediaOpt1 = mediaINT
224 ,mediaOpt2 = mediaINT + mediaCFG
225 ,mediaOpt3 = mediaINT + mediaCFG + mediaUSR
226 ,mediaOpt4 = mediaINT + mediaCFG + mediaUSR + mediaSYS
227 /* this is the flavor from pre-2.8.6 */
228 ,mediaALL = mediaINT + mediaEXT + mediaCFG + mediaUSR + mediaSYS
229 } AcceptMedia;
230
231 /*
232 * Options used for "Accept-Encoding:" string
233 */
234 typedef enum {
235 encodingNONE = 0
236 ,encodingGZIP = 1
237 ,encodingDEFLATE = 2
238 ,encodingCOMPRESS = 4
239 ,encodingBZIP2 = 8
240 ,encodingBROTLI = 16
241 ,encodingZSTD = 32
242 ,encodingALL = (encodingGZIP
243 + encodingDEFLATE
244 + encodingCOMPRESS
245 + encodingBZIP2
246 + encodingBROTLI
247 + encodingZSTD)
248 } AcceptEncoding;
249
250 /*
251
252 HTSetPresentation: Register a system command to present a format
253
254 ON ENTRY,
255
256 rep is the MIME - style format name
257
258 command is the MAILCAP - style command template
259
260 testcommand is the MAILCAP - style testcommand template
261
262 quality A degradation faction 0..1.0
263
264 secs A limit on the time user will wait (0.0 for infinity)
265 secs_per_byte
266
267 maxbytes A limit on the length acceptable as input (0 infinite)
268
269 media Used in filtering presentation types for "Accept:"
270
271 */
272 extern void HTSetPresentation(const char *representation,
273 const char *command,
274 const char *testcommand,
275 double quality,
276 double secs,
277 double secs_per_byte,
278 long int maxbytes,
279 AcceptMedia media
280 );
281
282 /*
283
284 HTSetConversion: Register a conversion routine
285
286 ON ENTRY,
287
288 rep_in is the content-type input
289
290 rep_out is the resulting content-type
291
292 converter is the routine to make the stream to do it
293
294 */
295
296 extern void HTSetConversion(const char *rep_in,
297 const char *rep_out,
298 HTConverter *converter,
299 double quality,
300 double secs,
301 double secs_per_byte,
302 long int maxbytes,
303 AcceptMedia media
304 );
305
306 /*
307
308 HTStreamStack: Create a stack of streams
309
310 This is the routine which actually sets up the conversion. It currently
311 checks only for direct conversions, but multi-stage conversions are forseen.
312 It takes a stream into which the output should be sent in the final format,
313 builds the conversion stack, and returns a stream into which the data in the
314 input format should be fed. The anchor is passed because hypertxet objects
315 load information into the anchor object which represents them.
316
317 */
318 extern HTStream *HTStreamStack(HTFormat format_in,
319 HTFormat format_out,
320 HTStream *stream_out,
321 HTParentAnchor *anchor);
322
323 /*
324 HTReorderPresentation: put presentation near head of list
325
326 Look up a presentation (exact match only) and, if found, reorder it to the
327 start of the HTPresentations list. - kw
328 */
329
330 extern void HTReorderPresentation(HTFormat format_in,
331 HTFormat format_out);
332
333 /*
334 * Setup 'get_accept' flag to denote presentations that are not redundant,
335 * and will be listed in "Accept:" header.
336 */
337 extern void HTFilterPresentations(void);
338
339 /*
340
341 HTStackValue: Find the cost of a filter stack
342
343 Must return the cost of the same stack which HTStreamStack would set up.
344
345 ON ENTRY,
346
347 format_in The format of the data to be converted
348
349 format_out The format required
350
351 initial_value The intrinsic "value" of the data before conversion on a scale
352 from 0 to 1
353
354 length The number of bytes expected in the input format
355
356 */
357 extern float HTStackValue(HTFormat format_in,
358 HTFormat rep_out,
359 double initial_value,
360 long int length);
361
362 #define NO_VALUE_FOUND -1e20 /* returned if none found */
363
364 /* Display the page while transfer in progress
365 * -------------------------------------------
366 *
367 * Repaint the page only when necessary.
368 * This is a traverse call for HText_pageDispaly() - it works!.
369 *
370 */
371 extern void HTDisplayPartial(void);
372
373 extern void HTFinishDisplayPartial(void);
374
375 /*
376
377 HTCopy: Copy a socket to a stream
378
379 This is used by the protocol engines to send data down a stream, typically
380 one which has been generated by HTStreamStack.
381
382 */
383 extern int HTCopy(HTParentAnchor *anchor,
384 int file_number,
385 void *handle,
386 HTStream *sink);
387
388 /*
389
390 HTFileCopy: Copy a file to a stream
391
392 This is used by the protocol engines to send data down a stream, typically
393 one which has been generated by HTStreamStack. It is currently called by
394 HTParseFile
395
396 */
397 extern int HTFileCopy(FILE *fp,
398 HTStream *sink);
399
400 #ifdef USE_SOURCE_CACHE
401 /*
402
403 HTMemCopy: Copy a memory chunk to a stream
404
405 This is used by the protocol engines to send data down a stream, typically
406 one which has been generated by HTStreamStack. It is currently called by
407 HTParseMem
408
409 */
410 extern int HTMemCopy(HTChunk *chunk,
411 HTStream *sink);
412 #endif
413
414 /*
415
416 HTCopyNoCR: Copy a socket to a stream, stripping CR characters.
417
418 It is slower than HTCopy .
419
420 */
421
422 extern void HTCopyNoCR(HTParentAnchor *anchor,
423 int file_number,
424 HTStream *sink);
425
426 /*
427
428 Clear input buffer and set file number
429
430 This routine and the one below provide simple character input from sockets.
431 (They are left over from the older architecture and may not be used very
432 much.) The existence of a common routine and buffer saves memory space in
433 small implementations.
434
435 */
436 extern void HTInitInput(int file_number);
437
438 /*
439
440 Get next character from buffer
441
442 */
443 extern int interrupted_in_htgetcharacter;
444 extern int HTGetCharacter(void);
445
446 /*
447
448 HTParseSocket: Parse a socket given its format
449
450 This routine is called by protocol modules to load an object. uses
451 HTStreamStack and the copy routines above. Returns HT_LOADED if successful,
452 <0 if not.
453
454 */
455 extern int HTParseSocket(HTFormat format_in,
456 HTFormat format_out,
457 HTParentAnchor *anchor,
458 int file_number,
459 HTStream *sink);
460
461 /*
462
463 HTParseFile: Parse a File through a file pointer
464
465 This routine is called by protocols modules to load an object. uses
466 HTStreamStack and HTFileCopy. Returns HT_LOADED if successful, can also
467 return HT_PARTIAL_CONTENT, HT_NO_DATA, or other <0 for failure.
468
469 */
470 extern int HTParseFile(HTFormat format_in,
471 HTFormat format_out,
472 HTParentAnchor *anchor,
473 FILE *fp,
474 HTStream *sink);
475
476 #ifdef USE_SOURCE_CACHE
477 /*
478
479 HTParseMem: Parse a document in memory
480
481 This routine is called by protocols modules to load an object. uses
482 HTStreamStack and HTMemCopy. Returns HT_LOADED if successful, can also
483 return <0 for failure.
484
485 */
486 extern int HTParseMem(HTFormat format_in,
487 HTFormat format_out,
488 HTParentAnchor *anchor,
489 HTChunk *chunk,
490 HTStream *sink);
491 #endif
492
493 #ifdef USE_ZLIB
494 /*
495 HTParseGzFile: Parse a gzip'ed File through a file pointer
496
497 This routine is called by protocols modules to load an object. uses
498 HTStreamStack and HTGzFileCopy. Returns HT_LOADED if successful, can also
499 return HT_PARTIAL_CONTENT, HT_NO_DATA, or other <0 for failure.
500 */
501 extern int HTParseGzFile(HTFormat format_in,
502 HTFormat format_out,
503 HTParentAnchor *anchor,
504 gzFile gzfp,
505 HTStream *sink);
506
507 /*
508 HTParseZzFile: Parse a deflate'd File through a file pointer
509
510 This routine is called by protocols modules to load an object. uses
511 HTStreamStack and HTZzFileCopy. Returns HT_LOADED if successful, can also
512 return HT_PARTIAL_CONTENT, HT_NO_DATA, or other <0 for failure.
513 */
514 extern int HTParseZzFile(HTFormat format_in,
515 HTFormat format_out,
516 HTParentAnchor *anchor,
517 FILE *zzfp,
518 HTStream *sink);
519
520 #endif /* USE_ZLIB */
521
522 #ifdef USE_BZLIB
523 /*
524 HTParseBzFile: Parse a bzip2'ed File through a file pointer
525
526 This routine is called by protocols modules to load an object. uses
527 HTStreamStack and HTBzFileCopy. Returns HT_LOADED if successful, can also
528 return HT_PARTIAL_CONTENT, HT_NO_DATA, or other <0 for failure.
529 */
530 extern int HTParseBzFile(HTFormat format_in,
531 HTFormat format_out,
532 HTParentAnchor *anchor,
533 BZFILE * bzfp,
534 HTStream *sink);
535
536 #endif /* USE_BZLIB */
537
538 #ifdef USE_BROTLI
539 /*
540 HTParseBrFile: Parse a brotli'ed File through a file pointer
541
542 This routine is called by protocols modules to load an object. uses
543 HTStreamStack and HTBrFileCopy. Returns HT_LOADED if successful, can also
544 return HT_PARTIAL_CONTENT, HT_NO_DATA, or other <0 for failure.
545 */
546 extern int HTParseBrFile(HTFormat format_in,
547 HTFormat format_out,
548 HTParentAnchor *anchor,
549 FILE *brfp,
550 HTStream *sink);
551
552 #endif /* USE_BROTLI */
553
554 #ifdef USE_ZSTD
555 /*
556 HTParseZstdFile: Parse a zstd'ed File through a file pointer
557
558 This routine is called by protocols modules to load an object. uses
559 HTStreamStack and HTZstdFileCopy. Returns HT_LOADED if successful, can also
560 return HT_PARTIAL_CONTENT, HT_NO_DATA, or other <0 for failure.
561 */
562 extern int HTParseZstdFile(HTFormat format_in,
563 HTFormat format_out,
564 HTParentAnchor *anchor,
565 FILE *brfp,
566 HTStream *sink);
567 #endif /* USE_ZSTD */
568
569 /*
570
571 HTNetToText: Convert Net ASCII to local representation
572
573 This is a filter stream suitable for taking text from a socket and passing
574 it into a stream which expects text in the local C representation. It does
575 ASCII and newline conversion. As usual, pass its output stream to it when
576 creating it.
577
578 */
579 extern HTStream *HTNetToText(HTStream *sink);
580
581 /*
582
583 HTFormatInit: Set up default presentations and conversions
584
585 These are defined in HTInit.c or HTSInit.c if these have been replaced. If
586 you don't call this routine, and you don't define any presentations, then
587 this routine will automatically be called the first time a conversion is
588 needed. However, if you explicitly add some conversions (eg using
589 HTLoadRules) then you may want also to explicitly call this to get the
590 defaults as well.
591
592 */
593 extern void HTFormatInit(void);
594
595 /*
596
597 Epilogue
598
599 */
600 extern BOOL HTOutputSource; /* Flag: shortcut parser */
601
602 #ifdef __cplusplus
603 }
604 #endif
605 #endif /* HTFORMAT_H */