Annotation of libwww/Library/src/HTWWWStr.html, revision 2.18
2.1 frystyk 1: <HTML>
2: <HEAD>
2.7 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 18-May-1996 -->
4: <!-- Changed by: Eric Prud'hommeaux, 28-May-1996 -->
2.11 frystyk 5: <TITLE>W3C Sample Code Library libwww WWW String Utilities</TITLE>
2.1 frystyk 6: </HEAD>
7: <BODY>
2.5 frystyk 8: <H1>
9: WWW Related String Management
10: </H1>
2.1 frystyk 11: <PRE>
12: /*
13: ** (c) COPYRIGHT MIT 1995.
14: ** Please first read the full copyright statement in the file COPYRIGH.
15: */
16: </PRE>
2.5 frystyk 17: <P>
2.1 frystyk 18: This module is like the <A HREF="HTString.html">generic string utility
2.5 frystyk 19: module</A> but it contains more Web related string utility functions. Examples
20: are functions that return a <I>date string</I>, a <I>Message ID string</I>
21: etc.
22: <P>
23: This module is implemented by <A HREF="HTWWWStr.c">HTWWWStr.c</A>, and it
2.14 frystyk 24: is a part of the <A HREF="http://www.w3.org/Library/"> W3C Sample Code
2.5 frystyk 25: Library</A>.
2.1 frystyk 26: <PRE>
27: #ifndef HTWWWSTR_H
28: #define HTWWWSTR_H
2.5 frystyk 29:
30: #include "HTUser.h"
2.7 frystyk 31: #include "HTAtom.h"
2.18 ! vbancrof 32:
! 33: #ifdef __cplusplus
! 34: extern "C" {
! 35: #endif
2.1 frystyk 36: </PRE>
2.5 frystyk 37: <H2>
2.16 frystyk 38: MIME Parsing and other String Based Utilities
39: </H2>
40: <P>
41: A bunch of "finding the next whatever" functions.
42: <H3>
2.5 frystyk 43: Next word or quoted string
2.16 frystyk 44: </H3>
2.5 frystyk 45: <P>
46: This function returns a RFC822 word separated by space, comma, or semi-colons.
47: <CODE>pstr</CODE> points to a string containing a word separated by white
48: white space "," ";" or "=". The word can optionally be quoted using
49: <"> or "<" ">" Comments surrrounded by '(' ')' are filtered out. On exit,
50: <CODE>pstr</CODE> has been moved to the first delimiter past the field THE
51: STRING HAS BEEN MUTILATED by a 0 terminator. The function returns a pointer
52: to the first word or NULL on error
2.1 frystyk 53: <PRE>
54: extern char * HTNextField (char** pstr);
55: </PRE>
2.16 frystyk 56: <H3>
2.9 frystyk 57: Next Name-value Pair
2.16 frystyk 58: </H3>
2.9 frystyk 59: <P>
60: This is the same as <CODE>HTNextField</CODE> but it does not look for '='
61: as a separator so if there is a name-value pair then both parts are returned.
62: Returns a pointer to the first word or NULL on error
63: <PRE>
64: extern char * HTNextPair (char ** pstr);
65: </PRE>
2.12 frystyk 66: <H3>
2.17 frystyk 67: Next Name-value Parameter
68: </H3>
69: <P>
70: This is the same as <CODE>HTNextPair</CODE> but it does not look for ','
71: as a separator so if there is a name-value pair then both parts are returned.
72: Returns a pointer to the first word or NULL on error
73: <PRE>
74: extern char * HTNextParam (char ** pstr);
75: </PRE>
76: <H3>
2.13 frystyk 77: Next LWS Delimited Token
78: </H3>
2.16 frystyk 79: <P>
80: A simpler version of the above that only looks for linear white space as
81: the delimiter.
2.13 frystyk 82: <PRE>
83: extern char * HTNextLWSToken (char ** pstr);
84: </PRE>
85: <H3>
86: Find next "/" Delimited Segment
2.12 frystyk 87: </H3>
2.16 frystyk 88: <P>
89: This is the same as HTNextField but it includes "/" as a delimiter. Returns
90: a pointer to the first segment or NULL on error
2.12 frystyk 91: <PRE>
92: extern char * HTNextSegment (char ** pstr);
93: </PRE>
2.16 frystyk 94: <H3>
95: Next Comma Separated String (or Element)
96: </H3>
97: <P>
98: This is the same as HTNextPair but it does not look for anything else than
99: ',' as separator Returns a pointer to the first word or NULL on error
100: <PRE>
101: extern char * HTNextElement (char ** pstr);
102: </PRE>
103: <H3>
2.8 frystyk 104: Next S-expression
2.16 frystyk 105: </H3>
2.8 frystyk 106: <P>
107: Find the next s-expression token from a string of characters. We return the
108: <CODE>name</CODE> of this expression and the <CODE>param</CODE> points to
109: the parameters. Note, that the string has been mutilated by a 0 terminator!
110: <PRE>
111: extern char * HTNextSExp (char ** exp, char ** param);
112: </PRE>
113: <H2>
2.5 frystyk 114: Reading CRLF
115: </H2>
116: <P>
117: The Library provides a default set of read routines that can handle the most
118: common situations. However, before we start we make following definition
119: is to make life easier when having a state machine looking for a
120: <CODE><CRLF></CODE> sequence.
121: <PRE>
122: typedef enum _HTEOLState {
123: EOL_ERR = -1,
124: EOL_BEGIN = 0,
125: EOL_FCR,
126: EOL_FLF,
127: EOL_DOT,
128: EOL_SCR,
2.6 eric 129: EOL_SLF,
130: /* intermediate states */
131: EOL_END,
132: EOL_FOLD,
133: EOL_LINE
2.5 frystyk 134: } HTEOLState;
135: </PRE>
136: <H2>
137: RFC1123 Date/Time Stamp String
138: </H2>
139: <P>
2.10 frystyk 140: Returns a string containing a date/time stamp string in RFC-1123 format.
141: The string is in static memory so be aware!
2.1 frystyk 142: <PRE>
2.10 frystyk 143: extern const char * HTDateTimeStr (time_t *calendar, BOOL local);
2.1 frystyk 144: </PRE>
2.5 frystyk 145: <H2>
146: Date used for directory listings
147: </H2>
2.10 frystyk 148: <P>
149: Generates a date/time stamp string used in directory listings. There is nothing
150: special about this format, it is just to make directory listings look alike.
2.1 frystyk 151: <PRE>
152: extern BOOL HTDateDirStr (time_t * time, char * str, int len);
153: </PRE>
2.5 frystyk 154: <H2>
155: Parse a Date/Time String
156: </H2>
157: <P>
2.10 frystyk 158: Converts a variety of different string representations of date time stamps
159: in GMT to a local representation of localtime <CODE>time_t</CODE>. The local
160: <I>time zone</I> is taken from the <A HREF="HTUser.html">user profile</A>
161: information or directly from the system if <CODE>NULL</CODE> is passed as
162: user profile . If the time is relative (for example in the <CODE>Age</CODE>
163: header) then you can indicate whether it should be expanded to local time
164: or not by using the <CODE>expand</CODE> argument.
2.5 frystyk 165: <PRE>
2.9 frystyk 166: extern time_t HTParseTime (const char * str, HTUserProfile * up, BOOL expand);
2.5 frystyk 167: </PRE>
168: <H2>
169: Unique Message-ID String
170: </H2>
171: <P>
172: The message ID string can for example be use as a RFC 822 header. The content
173: is based on the information taken from the <A HREF="HTUser.html">user
2.10 frystyk 174: profile</A> which can be supplied by the application.
2.5 frystyk 175: <PRE>extern const char * HTMessageIdStr (HTUserProfile * up);
176: </PRE>
177: <H2>
2.7 frystyk 178: Matching MIME Content-Types
179: </H2>
180: <P>
181: Matches MIME constructions for <I>content-types</I> and others like them,
182: for example "text/html", "text/plain". It can also match wild cards like
183: "text/<star>" and "<star>/<star>. We use <star> instead of * in order note
184: to make C like comments :-)
185: <PRE>
186: extern BOOL HTMIMEMatch (HTAtom * tmplate, HTAtom * actual);
187: </PRE>
188: <H2>
2.5 frystyk 189: Converts an Integer to a String using Prefix
190: </H2>
191: <P>
192: In computer-world 1K is 1024 bytes and 1M is 1024K -- however, sprintf()
193: still formats in base-10. Therefore I output only until 999, and then start
194: using the next unit. This doesn't work wrong, it's just a feature. The conversion
195: is done in "str" which must be large enough to contain the result.
2.1 frystyk 196: <PRE>
197: extern void HTNumToStr (unsigned long n, char *str, int len);
198: </PRE>
2.5 frystyk 199: <H2>
200: Conversion between URLs and Local File Names
201: </H2>
202: <P>
203: These are two functions that separate the URL naming syntax from platform
204: dependent file naming schemes. If you are porting the code to a new platform,
205: you probably have to do some translation here.
206: <H3>
207: Convert file URLs into a local representation
208: </H3>
209: <P>
210: The URL has already been translated through the rules in get_physical in
211: HTAccess.c and all we need to do now is to map the path to a local
212: representation, for example if must translate '/' to the ones that turn the
213: wrong way ;-) Returns local file (that must be freed by caller) if OK, else
214: NULL.
215: <PRE>
216: extern char * HTWWWToLocal (const char * url, const char * base,
217: HTUserProfile * up);
218: </PRE>
219: <H3>
220: Convert a local file name into a URL
221: </H3>
222: <P>
2.16 frystyk 223: Generates a WWW URL name from a local file name or NULL if error. Returns
224: URL (that must be freed by caller) if OK, else NULL. The access parameter
225: can be used to indicate any special scheme used for local file access. If
226: NULL then "<CODE>file:</CODE>" is used.
2.1 frystyk 227: <PRE>
2.15 frystyk 228: extern char * HTLocalToWWW (const char * local, const char * access);
2.1 frystyk 229: </PRE>
230: <PRE>
2.18 ! vbancrof 231: #ifdef __cplusplus
! 232: }
2.1 frystyk 233: #endif
2.18 ! vbancrof 234:
! 235: #endif /* HTWWWSTR_H */
2.1 frystyk 236: </PRE>
2.5 frystyk 237: <P>
238: <HR>
2.4 frystyk 239: <ADDRESS>
2.18 ! vbancrof 240: @(#) $Id: HTWWWStr.html,v 2.17 1999/03/24 16:26:57 frystyk Exp $
2.4 frystyk 241: </ADDRESS>
2.5 frystyk 242: </BODY></HTML>
Webmaster