Annotation of libwww/Library/src/HTBind.html, revision 2.18

2.1       frystyk     1: <HTML>
                      2: <HEAD>
2.14      frystyk     3:   <!-- Changed by: Henrik Frystyk Nielsen,  5-Jun-1996 -->
2.15      frystyk     4:   <TITLE>W3C Sample Code Library libwww File Suffix Binding</TITLE>
2.1       frystyk     5: </HEAD>
                      6: <BODY>
2.12      frystyk     7: <H1>
                      8:   File Suffix Binding Manager
                      9: </H1>
2.1       frystyk    10: <PRE>
                     11: /*
                     12: **     (c) COPYRIGHT MIT 1995.
                     13: **     Please first read the full copyright statement in the file COPYRIGH.
                     14: */
                     15: </PRE>
2.12      frystyk    16: <P>
2.18    ! frystyk    17: The preferences that we described in section
        !            18: <A HREF="../User/Using/Prefs.html">Request Preferences</A> did not mention
        !            19: what libwww should do if it doesn't know the data format of a document. In
        !            20: many protocols this information is provided by the remote server. Typical
        !            21: examples are MIME like protocols where the metainformation such as the
        !            22: <EM>Content-Type</EM> and the <EM>Content-Language</EM> is provided together
        !            23: with the document. However, applications often have access to the local file
        !            24: system using <B>file</B> URLs which in general do not keep any or at least
        !            25: very little information of the file type. It is therefore required to have
        !            26: some kind of binding between the file system and the preferences registered
        !            27: in the Library which provides this mateinformation about the object.
        !            28: <P>
        !            29: Often files in a file system is classified by some sort of a suffix, for
        !            30: example, <TT>GIF</TT> files are often ending in <EM>.gif</EM>, text files
        !            31: in <EM>.txt</EM> etc. This binding is not static and it is therefore required
        !            32: to have a dynamic binding just like the preferences themselves. An example
        !            33: of the latter is HTML files which on most Unix systems end in <EM>.html</EM>
        !            34: whereas they on many MS-DOS based systems end in <EM>.htm</EM>.
        !            35: <P>
        !            36: This module provides a generic binding mechanism between a file and its
        !            37: representation internally in libwww. It is not limited to simple file suffix
        !            38: classification but can also be used in more advanced environments using data
        !            39: bases etc. However, at this point we are interested in how we can register
        !            40: bindings between file suffixes and for example content types, content languages
        !            41: etc. The Bind manager is born with a certain knowledge about the set of
        !            42: delimiters but more can be added to provide the functionality desired.
        !            43: <P>
        !            44: All the binding management could of course be replaced by a database interface.
2.12      frystyk    45: <P>
                     46: This module is implemented by <A HREF="HTBind.c">HTBind.c</A>, and it is
2.17      frystyk    47: a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.12      frystyk    48: Library</A>.
2.1       frystyk    49: <PRE>
                     50: #ifndef HTBIND_H
                     51: #define HTBIND_H
                     52: 
                     53: #include "HTFormat.h"
                     54: #include "HTAnchor.h"
                     55: </PRE>
2.12      frystyk    56: <H2>
                     57:   Initialization of the Module
                     58: </H2>
                     59: <P>
                     60: These functions must be called on startup and termination of the application.
                     61: This is done automatically by <A HREF="HTReq.html#Library">HTLibInit() and
                     62: HTLibTerminate()</A>.
2.1       frystyk    63: <PRE>
2.6       frystyk    64: extern BOOL HTBind_init                (void);
                     65: extern BOOL HTBind_deleteAll   (void);
2.1       frystyk    66: </PRE>
2.12      frystyk    67: <H2>
                     68:   Case Sensitivity
                     69: </H2>
                     70: <P>
                     71: Should the search for suffixes be case sensitive or not? The default value
                     72: is <EM>case sensitive</EM>.
2.1       frystyk    73: <PRE>
2.6       frystyk    74: extern void HTBind_caseSensitive       (BOOL sensitive);
2.1       frystyk    75: </PRE>
2.12      frystyk    76: <H2>
                     77:   Suffix Delimiters
                     78: </H2>
                     79: <P>
                     80: Change the set of suffix delimiters. The default is a platform dependent
2.16      frystyk    81: set defined in the <A HREF="wwwsys.html">tcp module</A>.
2.1       frystyk    82: <PRE>
2.8       frystyk    83: extern const char *HTBind_delimiters   (void);
                     84: extern void HTBind_setDelimiters       (const char * new_suffixes);
2.1       frystyk    85: </PRE>
2.12      frystyk    86: <H2>
                     87:   Set up Bindings Associated with a File Suffix
                     88: </H2>
                     89: <P>
2.10      frystyk    90: There are four types of bindings:
2.1       frystyk    91: <UL>
2.12      frystyk    92:   <LI>
                     93:     Content Type (media type)
                     94:   <LI>
                     95:     Language
                     96:   <LI>
                     97:     Content Encoding
                     98:   <LI>
                     99:     Content Transfer Encoding
2.1       frystyk   100: </UL>
2.12      frystyk   101: <P>
2.1       frystyk   102: And the associated set of methods is defined as:
                    103: <PRE>
2.8       frystyk   104: extern BOOL HTBind_add         (const char *   suffix,
                    105:                                 const char *   representation,
                    106:                                 const char *   encoding,
2.10      frystyk   107:                                 const char *   transfer,
2.8       frystyk   108:                                 const char *   language,
2.6       frystyk   109:                                 double         value);
                    110: 
2.8       frystyk   111: extern BOOL HTBind_addType     (const char *   suffix,
                    112:                                 const char *   format,
2.6       frystyk   113:                                 double         value);
                    114: 
2.8       frystyk   115: extern BOOL HTBind_addEncoding (const char *   suffix,
                    116:                                 const char *   encoding,
2.6       frystyk   117:                                 double         value);
                    118: 
2.10      frystyk   119: extern BOOL HTBind_addTransfer (const char *   suffix,
                    120:                                 const char *   transfer,
                    121:                                 double         value);
                    122: 
2.8       frystyk   123: extern BOOL HTBind_addLanguage (const char *   suffix,
                    124:                                 const char *   language,
2.6       frystyk   125:                                 double         value);
2.1       frystyk   126: </PRE>
2.12      frystyk   127: <P>
                    128: The first method is a "super" method for binding information to a file suffic.
                    129: Any of the string values can be <CODE>NULL</CODE>. If filename suffix is
                    130: already defined its previous definition is overridden or modified. For example,
                    131: a <CODE>HTBind_setType</CODE> and <CODE>HTBind_setEncoding</CODE> can be
                    132: called with the same suffix.
                    133: <P>
                    134: Calling this with suffix set to "*" will set the default representation.
                    135: Calling this with suffix set to "*.*" will set the default representation
                    136: for unknown suffix files which contain a "."
                    137: <P>
                    138: <B>NOTE:</B> The suffixes <EM>can</EM> contain characters that must be escaped
                    139: in a URL. However, they should <EM>not</EM> be encoded when parsed as the
                    140: <CODE>suffix</CODE> parameter.
                    141: <H2>
                    142:   Determine a suitable suffix
                    143: </H2>
                    144: <P>
                    145: Use the set of bindings to find a suitable suffix (or index) for a certain
                    146: combination of language, media type and encoding given in the anchor. Returns
                    147: a pointer to a suitable suffix string that must be freed by the caller. If
                    148: more than one suffix is found they are all concatenated. If no suffix is
                    149: found, NULL is returned.
2.1       frystyk   150: <PRE>
2.6       frystyk   151: extern char * HTBind_getSuffix (HTParentAnchor * anchor);
2.1       frystyk   152: </PRE>
2.12      frystyk   153: <H2>
                    154:   Determine the content of an Anchor
                    155: </H2>
                    156: <P>
                    157: Use the set of bindings to find the combination of language, media type and
                    158: encoding of a given anchor. If more than one suffix is found they are all
                    159: searched. The last suffix has highest priority, the first one lowest. Returns
2.14      frystyk   160: the <A HREF="HTAnchor.html">HTAnchor object</A> with the representations
                    161: found. See also <CODE>HTBind_getFormat</CODE>
2.1       frystyk   162: <PRE>
2.14      frystyk   163: extern BOOL HTBind_getAnchorBindings   (HTParentAnchor * anchor);
                    164: </PRE>
                    165: <H2>
                    166:   Determine the content of a Response
                    167: </H2>
                    168: <P>
                    169: Use the set of bindings to find the combination of language, media type and
                    170: encoding of a given anchor. If more than one suffix is found they are all
                    171: searched. The last suffix has highest priority, the first one lowest. Returns
                    172: the <A HREF="HTResponse.html">HTResponse object</A> with the representations
                    173: found. See also <CODE>HTBind_getFormat</CODE>
                    174: <PRE>
                    175: extern BOOL HTBind_getResponseBindings (HTResponse * response,
                    176:                                          const char * url);
2.1       frystyk   177: </PRE>
2.12      frystyk   178: <H2>
                    179:   Determine the content of File
                    180: </H2>
                    181: <P>
                    182: Use the set of bindings to find the combination of language, media type and
                    183: encoding of a given anchor. If more than one suffix is found they are all
                    184: searched. The last suffix has highest priority, the first one lowest. Returns
                    185: the format, encoding, and language found. See also
2.1       frystyk   186: <CODE>HTBind_getBindings</CODE>.
                    187: <PRE>
2.10      frystyk   188: extern BOOL HTBind_getFormat (const char *     filename,
                    189:                              HTFormat *        format,
                    190:                              HTEncoding *      enc,
2.11      frystyk   191:                              HTEncoding *      cte,
2.10      frystyk   192:                              HTLanguage *      lang,
                    193:                              double *          quality);
2.1       frystyk   194: </PRE>
2.12      frystyk   195: <P>
2.1       frystyk   196: End of declaration module
                    197: <PRE>
                    198: #endif /* HTBIND_H */
                    199: </PRE>
2.12      frystyk   200: <P>
                    201:   <HR>
2.10      frystyk   202: <ADDRESS>
2.18    ! frystyk   203:   @(#) $Id: HTBind.html,v 2.17 1998/05/14 02:10:17 frystyk Exp $
2.10      frystyk   204: </ADDRESS>
2.12      frystyk   205: </BODY></HTML>

Webmaster