Annotation of libwww/Library/src/HTFormat.html, revision 2.67
2.10 timbl 1: <HTML>
2: <HEAD>
2.67 ! frystyk 3: <TITLE>W3C Reference Library libwww Format Negotiation</TITLE>
2.10 timbl 4: </HEAD>
2.1 timbl 5: <BODY>
2.67 ! frystyk 6: <H1>
! 7: The Format Manager
! 8: </H1>
2.33 frystyk 9: <PRE>
10: /*
2.41 frystyk 11: ** (c) COPYRIGHT MIT 1995.
2.33 frystyk 12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
2.67 ! frystyk 15: <P>
! 16: The Format Manager is responsible for setting up the stream pipe from the
! 17: <A HREF="HTChannl.html">Channel Object</A> to the <A HREF="HTReq.html">Request
! 18: Object</A> when data is arriving, for example as a response to s
! 19: <A HREF="HTTP.html">HTTP</A> <B>Get</B> request. As data arrives, we start
! 20: to parse it and the more we know the more we can build up our stream pipe.
! 21: For example, in the case of HTTP, we first have a stream that can parse the
! 22: HTTP response line containing "<CODE>200 OK</CODE>". Then we have a
! 23: <A HREF="HTMIME.html">MIME parser</A> for handling the MIME headers. When
! 24: the MIME headers have been parsed, we know the content type and any encoding
! 25: of the MIME body. If we need to decode a chunked encoding then we set up
! 26: a chunked decoder, and if we have to parse a HTML object then we set up a
! 27: HTML parser.
! 28: <P>
! 29: The Format Manager is also responsible for keeping track of the
! 30: "<I>preferences</I>" of the application and/or user. It is an integral part
! 31: of the Web and HTTP, that the client application can express its preferences
! 32: as a set of "accept" headers in a HTTP request. This task is highly related
! 33: to the task mentioned above as we there use the modules that are registered
! 34: and here tell the remote server what we are capable of doing and what we
! 35: would prefer.
! 36: <P>
! 37: <B>Note</B>: The library <B>core</B> does not define any default decoders
! 38: or parsers - they are all considered part of the application. The library
! 39: comes with a default set of parsers including the ones mentioned above which
! 40: can be initiated using the functions in <A HREF="HTInit.html">HTInit
! 41: module</A>. There are different initialization functions for content type
! 42: parsers and content encodings respectively.
! 43: <P>
! 44: Currently there are four dimensions for handling "accept" headers:
! 45: <P>
! 46: <UL>
! 47: <LI>
! 48: <A HREF="#type">Content Type Converters and Presenters</A>
! 49: <LI>
! 50: <A HREF="#encoding">Content Encoders and Decoders</A>
! 51: <LI>
! 52: <A HREF="#charset">Content Charsets</A>
! 53: <LI>
! 54: <A HREF="#language">Natural Languages</A>
! 55: </UL>
! 56: <P>
! 57: The application can assign its preferences in two ways: either <I>locally</I>
! 58: to a single request or <I>globally</I> to all requests. The local assignment
! 59: can either <I>add to </I>or <I>override</I> the global settings depending
! 60: on how they are registered. All local registration is handled by the
! 61: <A HREF="HTReq.html">Request Object</A> and the global registration is handled
! 62: by the Format Manager
! 63: <P>
! 64: <UL>
! 65: <LI>
! 66: <A HREF="#global">Global Preferences</A>
! 67: </UL>
! 68: <P>
! 69: When data is arriving and the Format Manager is to build a stream pipe from
! 70: the <A HREF="HTChannl.html">HTChannel Object</A> to the
! 71: <A HREF="HTReq.html">Request Object</A>, it uses a special set of <I>stream
! 72: stack algorithms</I>. These algorithms take the complete set of content type
! 73: converters, for example, and finds the one best suited for the task. We currently
! 74: have three stream stack algorithms: one for content types, one for content
! 75: encodings, and one for content transfer encodings:
! 76: <P>
! 77: <UL>
! 78: <LI>
! 79: <A HREF="#CTStack">The Content Type Stream Stack</A>
! 80: <LI>
! 81: <A HREF="#CEStack">The Content Encoding Stream Stack</A>
! 82: <LI>
! 83: <A HREF="#CTEStack">The Content Transfer Encoding Stream Stack</A>
! 84: </UL>
! 85: <P>
! 86: As part of the HTTP content negotiation, a server must be able to match the
! 87: preferences sent by the client in an HTTP request with the possible set of
! 88: documents that it has avaiable fro this URL. For example , it may have an
! 89: English and a Danish version in which case it looks at the Accept-Language
! 90: header and sees what the client prefers. The Library has a simple "Match"
! 91: algorithm for finding the best match.
! 92: <P>
2.31 frystyk 93: <UL>
2.67 ! frystyk 94: <LI>
! 95: <A HREF="#ranking">Content negotiation</A>
2.31 frystyk 96: </UL>
2.67 ! frystyk 97: <P>
! 98: This module is implemented by <A HREF="HTFormat.c">HTFormat.c</A>, and it
! 99: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C Reference
! 100: Library</A>.
2.31 frystyk 101: <PRE>
102: #ifndef HTFORMAT_H
2.1 timbl 103: #define HTFORMAT_H
104:
2.63 frystyk 105: #include "<A HREF="HTUtils.html">HTUtils.h</A>"
106: #include "<A HREF="HTStream.html">HTStream.h</A>"
107: #include "<A HREF="HTAtom.html">HTAtom.h</A>"
108: #include "<A HREF="HTList.html">HTList.h</A>"
109: #include "<A HREF="HTAnchor.html">HTAnchor.h</A>"
110: #include "<A HREF="HTReq.html">HTReq.h</A>"
2.31 frystyk 111: </PRE>
2.67 ! frystyk 112: <H2>
! 113: <A NAME="type">Content Type Converters and Presenters</A>
! 114: </H2>
! 115: <P>
! 116: All content type converters are subclassed from the Generic stream objetc.
! 117: That way, we allow the application to do very fast progressive display of
! 118: incoming data. In other words, the stream model of the Library provides data
! 119: as soon as it arrives from the network, the application does not have to
! 120: wait until the whole document has been down loaded before it starts parsing
! 121: it.
! 122: <H3>
! 123: Content Type Converters
! 124: </H3>
! 125: <P>
! 126: A <CODE>converter</CODE> is a stream with a special set of parameters and
! 127: which is registered as capable of converting from a MIME type to something
! 128: else (maybe another MIME-type). A converter is defined to be a function returning
! 129: a stream and accepting the following parameters. The content type elements
! 130: are atoms for which we have defined a prototype.
2.31 frystyk 131: <PRE>
2.52 frystyk 132: typedef HTStream * HTConverter (HTRequest * request,
133: void * param,
134: HTFormat input_format,
135: HTFormat output_format,
136: HTStream * output_stream);
2.42 frystyk 137: </PRE>
2.67 ! frystyk 138: <H3>
! 139: The HTPresentation Object
! 140: </H3>
! 141: <P>
! 142: A <CODE>presenter</CODE> is a module (possibly an external program) which
! 143: can present a graphic object of a certain MIME type to the user. That is,
! 144: <CODE>presenters</CODE> are normally used to present objects that the
! 145: <CODE>converters</CODE> are not able to handle. Data is transferred to the
! 146: external program using for example the
! 147: <A HREF="HTFWrite.html">HTSaveAndExecute</A> stream which writes to a local
! 148: file. Both presenters and converters are of the type
! 149: <A HREF="#converter">HTConverter</A>.
2.31 frystyk 150: <PRE>
2.42 frystyk 151: typedef struct _HTPresentation {
152: HTFormat rep; /* representation name atomized */
153: HTFormat rep_out; /* resulting representation */
154: HTConverter *converter; /* The routine to gen the stream stack */
155: char * command; /* MIME-format string */
156: char * test_command; /* MIME-format string */
157: double quality; /* Between 0 (bad) and 1 (good) */
158: double secs;
159: double secs_per_byte;
160: } HTPresentation;
2.28 frystyk 161: </PRE>
2.67 ! frystyk 162: <H3>
! 163: Basic Content type Converters
! 164: </H3>
! 165: <P>
! 166: We have a small set of basic converters that can be hooked in anywhere. They
! 167: don't "convert" anything but are nice to have.
! 168: <PRE>extern HTConverter HTThroughLine;
2.63 frystyk 169: extern HTConverter HTBlackHoleConverter;
170: </PRE>
2.67 ! frystyk 171: <H3>
! 172: Predefined Content Types
! 173: </H3>
! 174: <P>
! 175: These macros (which used to be constants) define some basic internally referenced
! 176: representations. The <CODE>www/xxx</CODE> ones are of course not MIME standard.
! 177: They are internal representations used in the Library but they can't be exported
! 178: to other apps!
2.28 frystyk 179: <PRE>
2.57 frystyk 180: #define WWW_RAW HTAtom_for("www/void") /* Raw output from Protocol */
2.28 frystyk 181: </PRE>
2.67 ! frystyk 182: <P>
! 183: <CODE>WWW_RAW</CODE> is an output format which leaves the input untouched
! 184: <EM>exactly</EM> as it is received by the protocol module. For example, in
! 185: the case of FTP, this format returns raw ASCII objects for directory listings;
! 186: for HTTP, everything including the header is returned, for Gopher, a raw
! 187: ASCII object is returned for a menu etc.
! 188: <PRE>
! 189: #define WWW_SOURCE HTAtom_for("*/*")
! 190: </PRE>
! 191: <P>
! 192: <CODE>WWW_SOURCE</CODE> is an output format which leaves the input untouched
! 193: <EM>exactly</EM> as it is received by the protocol module <B>IF</B> not a
! 194: suitable converter has been registered with a quality factor higher than
! 195: 1 (for example 2). In this case the <EM>SUPER CONVERTER</EM> is preferred
! 196: for the raw output. This can be used as a filter effect that allows conversion
! 197: from, for example raw FTPdirectory listings into HTML but passes a MIME body
! 198: untouched.
! 199: <PRE>
! 200: #define WWW_PRESENT HTAtom_for("www/present")
! 201: </PRE>
! 202: <P>
! 203: <CODE>WWW_PRESENT</CODE> represents the user's perception of the document.
! 204: If you convert to <CODE>WWW_PRESENT</CODE>, you present the material to the
! 205: user.
2.58 frystyk 206: <PRE>
207: #define WWW_DEBUG HTAtom_for("www/debug")
208: </PRE>
2.67 ! frystyk 209: <P>
! 210: <CODE>WWW_DEBUG</CODE> represents the user's perception of debug information,
! 211: for example sent as a HTML document in a HTTP redirection message.
2.28 frystyk 212: <PRE>
2.52 frystyk 213: #define WWW_UNKNOWN HTAtom_for("www/unknown")
2.28 frystyk 214: </PRE>
2.67 ! frystyk 215: <P>
! 216: <CODE>WWW_UNKNOWN</CODE> is a really unknown type. It differs from the real
! 217: MIME type <EM>"application/octet-stream"</EM> in that we haven't even tried
! 218: to figure out the content type at this point.
! 219: <P>
2.31 frystyk 220: These are regular MIME types defined. Others can be added!
2.28 frystyk 221: <PRE>
2.52 frystyk 222: #define WWW_HTML HTAtom_for("text/html")
2.28 frystyk 223: #define WWW_PLAINTEXT HTAtom_for("text/plain")
2.52 frystyk 224:
225: #define WWW_MIME HTAtom_for("message/rfc822")
2.60 frystyk 226: #define WWW_MIME_HEAD HTAtom_for("message/x-rfc822-head")
2.65 frystyk 227: #define WWW_MIME_FOOT HTAtom_for("message/x-rfc822-foot")
2.52 frystyk 228:
2.10 timbl 229: #define WWW_AUDIO HTAtom_for("audio/basic")
2.52 frystyk 230:
2.26 frystyk 231: #define WWW_VIDEO HTAtom_for("video/mpeg")
2.52 frystyk 232:
2.66 frystyk 233: #define WWW_GIF HTAtom_for("image")
2.63 frystyk 234: #define WWW_JPEG HTAtom_for("image/jpeg")
235: #define WWW_TIFF HTAtom_for("image/tiff")
2.52 frystyk 236: #define WWW_PNG HTAtom_for("image/png")
237:
238: #define WWW_BINARY HTAtom_for("application/octet-stream")
239: #define WWW_POSTSCRIPT HTAtom_for("application/postscript")
240: #define WWW_RICHTEXT HTAtom_for("application/rtf")
2.48 frystyk 241: </PRE>
2.67 ! frystyk 242: <P>
! 243: We also have some MIME types that come from the various protocols when we
! 244: convert from ASCII to HTML.
2.48 frystyk 245: <PRE>
246: #define WWW_GOPHER_MENU HTAtom_for("text/x-gopher")
2.53 frystyk 247: #define WWW_CSO_SEARCH HTAtom_for("text/x-cso")
2.48 frystyk 248:
249: #define WWW_FTP_LNST HTAtom_for("text/x-ftp-lnst")
250: #define WWW_FTP_LIST HTAtom_for("text/x-ftp-list")
251:
252: #define WWW_NNTP_LIST HTAtom_for("text/x-nntp-list")
253: #define WWW_NNTP_OVER HTAtom_for("text/x-nntp-over")
254: #define WWW_NNTP_HEAD HTAtom_for("text/x-nntp-head")
2.59 frystyk 255:
256: #define WWW_HTTP HTAtom_for("text/x-http")
2.55 frystyk 257: </PRE>
2.67 ! frystyk 258: <P>
! 259: Finally we have defined a special format for our RULE files as they can be
! 260: handled by a special converter.
2.55 frystyk 261: <PRE>
2.57 frystyk 262: #define WWW_RULES HTAtom_for("application/x-www-rules")
2.28 frystyk 263: </PRE>
2.67 ! frystyk 264: <H3>
! 265: Register Presenters
! 266: </H3>
! 267: <P>
! 268: This function creates a presenter object and adds to the list of conversions.
! 269: These are the parameters :
2.1 timbl 270: <DL>
2.67 ! frystyk 271: <DT>
! 272: conversions
! 273: <DD>
! 274: The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
! 275: <DT>
! 276: rep_in
! 277: <DD>
! 278: the MIME-style format name
! 279: <DT>
! 280: rep_out
! 281: <DD>
! 282: is the resulting content-type after the conversion
! 283: <DT>
! 284: converter
! 285: <DD>
! 286: is the routine to call which actually does the conversion
! 287: <DT>
! 288: quality
! 289: <DD>
! 290: A degradation faction [0..1]
! 291: <DT>
! 292: maxbytes
! 293: <DD>
! 294: A limit on the length acceptable as input (0 infinite)
! 295: <DT>
! 296: maxsecs
! 297: <DD>
! 298: A limit on the time user will wait (0 for infinity)
2.1 timbl 299: </DL>
2.31 frystyk 300: <PRE>
2.49 frystyk 301: extern void HTPresentation_add (HTList * conversions,
2.61 frystyk 302: const char * representation,
303: const char * command,
304: const char * test_command,
2.49 frystyk 305: double quality,
306: double secs,
307: double secs_per_byte);
2.1 timbl 308:
2.50 frystyk 309: extern void HTPresentation_deleteAll (HTList * list);
310: </PRE>
2.67 ! frystyk 311: <H3>
! 312: Register Converters
! 313: </H3>
! 314: <P>
! 315: This function creates a presenter object and adds to the list of conversions.
2.1 timbl 316: <DL>
2.67 ! frystyk 317: <DT>
! 318: conversions
! 319: <DD>
! 320: The list of <CODE>conveters</CODE> and <CODE>presenters</CODE>
! 321: <DT>
! 322: rep_in
! 323: <DD>
! 324: the MIME-style format name
! 325: <DT>
! 326: rep_out
! 327: <DD>
! 328: is the resulting content-type after the conversion
! 329: <DT>
! 330: converter
! 331: <DD>
! 332: is the routine to call which actually does the conversion
! 333: <DT>
! 334: quality
! 335: <DD>
! 336: A degradation faction [0..1]
! 337: <DT>
! 338: maxbytes
! 339: <DD>
! 340: A limit on the length acceptable as input (0 infinite)
! 341: <DT>
! 342: maxsecs
! 343: <DD>
! 344: A limit on the time user will wait (0 for infinity)
2.1 timbl 345: </DL>
346: <PRE>
2.49 frystyk 347: extern void HTConversion_add (HTList * conversions,
2.61 frystyk 348: const char * rep_in,
349: const char * rep_out,
2.49 frystyk 350: HTConverter * converter,
351: double quality,
352: double secs,
353: double secs_per_byte);
2.63 frystyk 354:
355: extern void HTConversion_deleteAll (HTList * list);
2.42 frystyk 356: </PRE>
2.67 ! frystyk 357: <H2>
! 358: <A NAME="encoding">Content and Transfer Encoders and Decoders</A>
! 359: </H2>
! 360: <P>
! 361: Content codins are transformations applied to an entity object after it was
! 362: created in its original form. The Library handles two types of codings:
2.64 frystyk 363: <DL>
2.67 ! frystyk 364: <DT>
! 365: <B>Content Codings</B>
! 366: <DD>
! 367: Content codings values indicate an encoding transformation that has been
! 368: applied to a resource. Content cosings are primarily used to allow a document
! 369: to be compressed or encrypted without loosing the identity of its underlying
! 370: media type.
! 371: <DT>
! 372: <B>Content Transfer Codings</B>
! 373: <DD>
! 374: Content transfer codings values are used to indicate an encoding transformation
! 375: that has been, can be, or may be need to be applied to an enity body in order
! 376: to ensure safe transport through the network. This differs from a content
! 377: coding in that the transfer coding is a property of the message, not the
! 378: original message.
2.64 frystyk 379: </DL>
2.67 ! frystyk 380: <P>
! 381: Both types of encodings use the same registration mechanism in the Library
! 382: which we describe below:
! 383: <H3>
! 384: Encoders and Decoders
! 385: </H3>
! 386: <P>
! 387: <EM>Encoders</EM> and <EM>decoders</EM> are subclassed from the
! 388: <A HREF="HTStream.html">generic stream class</A>. <EM>Encoders</EM> are capable
! 389: of adding a content coding to a data object and <EM>decoders</EM> can remove
! 390: a content coding.
2.50 frystyk 391: <PRE>
2.64 frystyk 392: typedef HTStream * HTCoder (HTRequest * request,
393: void * param,
394: HTEncoding coding,
395: HTStream * target);
2.50 frystyk 396: </PRE>
2.67 ! frystyk 397: <P>
! 398: The <EM>encoding</EM> is the name of the encoding mechanism reporesented
! 399: as an <A HREF="HTAtom.html">atom</A>, for example "zip", "chunked", etc.
! 400: Encodings are registered in lists and content encodings are separated from
! 401: transfer encodings by registering them in different lists.
! 402: <H3>
! 403: The HTCoding Object
! 404: </H3>
! 405: <P>
! 406: The <EM>HTCoding</EM> object represents a registered encoding together with
! 407: a encoder and a decoder.
2.63 frystyk 408: <PRE>
2.64 frystyk 409: typedef struct _HTCoding HTCoding;
2.63 frystyk 410: </PRE>
2.67 ! frystyk 411: <P>
! 412: Predefined Coding Types We have a set of pre defined atoms for various types
! 413: of content encodings and transfer encodings. "chunked" is not exactly in
! 414: the same group as the other encodings such as "binary" but it really doesn't
! 415: make any difference as it is just a matter of how the words are chosen. The
! 416: first three transfer encodings are actually not encodings - they are just
! 417: left overs from brain dead mail systems.
2.42 frystyk 418: <PRE>
2.63 frystyk 419: #define WWW_CTE_7BIT HTAtom_for("7bit")
420: #define WWW_CTE_8BIT HTAtom_for("8bit")
421: #define WWW_CTE_BINARY HTAtom_for("binary")
2.64 frystyk 422:
2.63 frystyk 423: #define WWW_CTE_BASE64 HTAtom_for("base64")
424: #define WWW_CTE_MACBINHEX HTAtom_for("macbinhex")
2.64 frystyk 425: #define WWW_CTE_CHUNKED HTAtom_for("chunked")
2.63 frystyk 426:
427: #define WWW_CE_COMPRESS HTAtom_for("compress")
428: #define WWW_CE_GZIP HTAtom_for("gzip")
2.42 frystyk 429: </PRE>
2.67 ! frystyk 430: <H3>
! 431: Register Content Coders
! 432: </H3>
! 433: <P>
2.63 frystyk 434: There is no difference in registrering a content encoder or a content decoder,
435: it all depends on how you use the list of encoders/decoders.
2.42 frystyk 436: <PRE>
2.64 frystyk 437: extern BOOL HTCoding_add (HTList * list,
438: const char * encoding,
439: HTCoder * encoder,
440: HTCoder * decoder,
441: double quality);
2.63 frystyk 442:
2.64 frystyk 443: extern void HTCoding_deleteAll (HTList * list);
2.42 frystyk 444:
2.64 frystyk 445: extern const char * HTCoding_name (HTCoding * me);
2.42 frystyk 446: </PRE>
2.67 ! frystyk 447: <H2>
! 448: <A NAME="charset">Content Charsets</A>
! 449: </H2>
! 450: <H3>
! 451: Register a Charset
! 452: </H3>
2.42 frystyk 453: <PRE>
2.50 frystyk 454: extern void HTCharset_add (HTList * list,
2.61 frystyk 455: const char * charset,
2.50 frystyk 456: double quality);
2.42 frystyk 457: </PRE>
2.67 ! frystyk 458: <H3>
! 459: Delete a list of Charsets
! 460: </H3>
2.50 frystyk 461: <PRE>
2.63 frystyk 462: typedef struct _HTAcceptNode {
463: HTAtom * atom;
464: double quality;
465: } HTAcceptNode;
466: </PRE>
467: <PRE>
2.50 frystyk 468: extern void HTCharset_deleteAll (HTList * list);
469: </PRE>
2.67 ! frystyk 470: <H2>
! 471: <A NAME="language">Content Languages</A>
! 472: </H2>
! 473: <H3>
! 474: Register a Language
! 475: </H3>
2.31 frystyk 476: <PRE>
2.50 frystyk 477: extern void HTLanguage_add (HTList * list,
2.61 frystyk 478: const char * lang,
2.50 frystyk 479: double quality);
480: </PRE>
2.67 ! frystyk 481: <H3>
! 482: Delete a list of Languages
! 483: </H3>
2.50 frystyk 484: <PRE>
2.51 frystyk 485: extern void HTLanguage_deleteAll (HTList * list);
2.50 frystyk 486: </PRE>
2.67 ! frystyk 487: <P>
! 488: <H2>
! 489: <A NAME="global">Global Preferences</A>
! 490: </H2>
! 491: <P>
2.50 frystyk 492: There are two places where these preferences can be registered: in a
2.67 ! frystyk 493: <EM>global</EM> list valid for <B>all</B> requests and a <EM>local</EM> list
! 494: valid for a particular request only. These are valid for <EM>all</EM> requests.
! 495: See the <A HREF="HTReq.html">Request Manager</A> fro local sets.
! 496: <H3>
! 497: Converters and Presenters
! 498: </H3>
! 499: <P>
! 500: The <EM>global</EM> list of specific conversions which the format manager
! 501: can do in order to fulfill the request. There is also a
! 502: <A HREF="HTReq.html"><EM>local</EM></A> list of conversions which contains
! 503: a generic set of possible conversions.
2.50 frystyk 504: <PRE>
2.64 frystyk 505: extern void HTFormat_setConversion (HTList * list);
2.50 frystyk 506: extern HTList * HTFormat_conversion (void);
2.31 frystyk 507: </PRE>
2.67 ! frystyk 508: <H3>
! 509: Content Codings
! 510: </H3>
2.50 frystyk 511: <PRE>
2.64 frystyk 512: extern void HTFormat_setContentCoding (HTList * list);
513: extern HTList * HTFormat_contentCoding (void);
2.50 frystyk 514: </PRE>
2.67 ! frystyk 515: <H3>
! 516: Content Transfer Codings
! 517: </H3>
2.64 frystyk 518: <PRE>
519: extern void HTFormat_setTransferCoding (HTList * list);
520: extern HTList * HTFormat_transferCoding (void);
521: </PRE>
2.67 ! frystyk 522: <P>
! 523: We also define a macro to find out whether a transfer encoding is really
! 524: an encoding or whether it is just a "dummy" as for example 7bit, 8bit, and
! 525: binary.
2.64 frystyk 526: <PRE>
527: #define HTFormat_isUnityTransfer(me) \
528: ((me)==NULL \
529: || (me)==WWW_CTE_BINARY || (me)==WWW_CTE_7BIT || (me)==WWW_CTE_8BIT)
530: </PRE>
2.67 ! frystyk 531: <H3>
! 532: Content Languages
! 533: </H3>
2.50 frystyk 534: <PRE>
2.64 frystyk 535: extern void HTFormat_setLanguage (HTList * list);
2.50 frystyk 536: extern HTList * HTFormat_language (void);
537: </PRE>
2.67 ! frystyk 538: <H3>
! 539: Content Charsets
! 540: </H3>
2.31 frystyk 541: <PRE>
2.64 frystyk 542: extern void HTFormat_setCharset (HTList * list);
2.50 frystyk 543: extern HTList * HTFormat_charset (void);
2.31 frystyk 544: </PRE>
2.67 ! frystyk 545: <H3>
! 546: Delete All Global Lists
! 547: </H3>
! 548: <P>
2.50 frystyk 549: This is a convenience function that might make life easier.
2.34 frystyk 550: <PRE>
2.50 frystyk 551: extern void HTFormat_deleteAll (void);
2.34 frystyk 552: </PRE>
2.67 ! frystyk 553: <H2>
! 554: <A NAME="ranking">Ranking of Accepted Formats</A>
! 555: </H2>
! 556: <P>
! 557: This function is used when the best match among several possible documents
! 558: is to be found as a function of the accept headers sent in the client request.
2.31 frystyk 559: <PRE>
2.42 frystyk 560: typedef struct _HTContentDescription {
561: char * filename;
2.63 frystyk 562: HTFormat content_type;
563: HTLanguage content_language;
564: HTEncoding content_encoding;
2.64 frystyk 565: HTEncoding content_transfer;
2.42 frystyk 566: int content_length;
567: double quality;
568: } HTContentDescription;
569:
2.52 frystyk 570: extern BOOL HTRank (HTList * possibilities,
571: HTList * accepted_content_types,
572: HTList * accepted_content_languages,
573: HTList * accepted_content_encodings);
2.1 timbl 574: </PRE>
2.67 ! frystyk 575: <H2>
! 576: <A NAME="CTStack">The Content Type Stream Stack</A>
! 577: </H2>
! 578: <P>
! 579: This is the routine which actually sets up the content type conversion. It
! 580: currently checks only for direct conversions, but multi-stage conversions
! 581: are forseen. It takes a stream into which the output should be sent in the
! 582: final format, builds the conversion stack, and returns a stream into which
! 583: the data in the input format should be fed. If <CODE>guess</CODE> is true
! 584: and input format is <CODE>www/unknown</CODE>, try to guess the format by
! 585: looking at the first few bytes of the stream.
! 586: <P>
2.31 frystyk 587: <PRE>
2.52 frystyk 588: extern HTStream * HTStreamStack (HTFormat rep_in,
589: HTFormat rep_out,
590: HTStream * output_stream,
591: HTRequest * request,
592: BOOL guess);
2.1 timbl 593: </PRE>
2.67 ! frystyk 594: <H3>
! 595: Cost of a Stream Stack
! 596: </H3>
! 597: <P>
! 598: Must return the cost of the same stack which HTStreamStack would set up.
2.31 frystyk 599: <PRE>
2.52 frystyk 600: extern double HTStackValue (HTList * conversions,
601: HTFormat format_in,
602: HTFormat format_out,
603: double initial_value,
604: long int length);
2.64 frystyk 605: </PRE>
2.67 ! frystyk 606: <H2>
! 607: <A NAME="CEStack">Content Encoding Stream Stack</A>
! 608: </H2>
! 609: <P>
! 610: When creating a coding stream stack, it is important that we keep the right
! 611: order of encoders and decoders. As an example, the HTTP spec specifies that
! 612: the list in the <EM>Content-Encoding</EM> header follows the order in which
! 613: the encodings have been applied to the object. Internally, we represent the
! 614: content encodings as <A HREF="HTAtom.html">atoms</A> in a linked
! 615: <A HREF="HTList.html">list object</A>.
! 616: <P>
! 617: The creation of the content coding stack is not based on quality factors
! 618: as we don't have the freedom as with content types. When using content codings
! 619: we <EM>must</EM> apply the codings specified or fail.
2.64 frystyk 620: <PRE>
621: extern HTStream * HTContentCodingStack (HTEncoding coding,
622: HTStream * target,
623: HTRequest * request,
624: void * param,
625: BOOL encoding);
626: </PRE>
2.67 ! frystyk 627: <P>
! 628: Here you can provide a complete list instead of a single token. The list
! 629: has to be filled up in the order the _encodings_ are to be applied
2.64 frystyk 630: <PRE>
631: extern HTStream * HTContentEncodingStack (HTList * encodings,
632: HTStream * target,
633: HTRequest * request,
634: void * param);
635: </PRE>
2.67 ! frystyk 636: <P>
! 637: Here you can provide a complete list instead of a single token. The list
! 638: has to be in the order the _encodings_ were applied - that is, the same way
! 639: that _encodings_ are to be applied. This is all consistent with the order
! 640: of the Content-Encoding header.
2.64 frystyk 641: <PRE>
642: extern HTStream * HTContentDecodingStack (HTList * encodings,
643: HTStream * target,
644: HTRequest * request,
645: void * param);
646: </PRE>
2.67 ! frystyk 647: <P>
! 648: <H2>
! 649: <A NAME="CTEStack">Content Transfer Encoding Stream Stack</A>
! 650: </H2>
! 651: <P>
! 652: Creating the transfer content encoding stream stack is not based on quality
! 653: factors as we don't have the freedom as with content types. Specify whether
! 654: you you want encoding or decoding using the BOOL "encode" flag.
2.64 frystyk 655: <PRE>
656: extern HTStream * HTTransferCodingStack (HTEncoding encoding,
657: HTStream * target,
658: HTRequest * request,
659: void * param,
660: BOOL encode);
661: </PRE>
662: <PRE>
2.42 frystyk 663: #endif /* HTFORMAT */
2.38 frystyk 664: </PRE>
2.67 ! frystyk 665: <P>
! 666: <HR>
2.63 frystyk 667: <ADDRESS>
2.67 ! frystyk 668: @(#) $Id: HTFormat.html,v 2.66 1996/05/15 17:32:15 frystyk Exp $
2.63 frystyk 669: </ADDRESS>
2.67 ! frystyk 670: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTFormat.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src