Annotation of libwww/Library/src/HTUtils.html, revision 2.88
2.6 timbl 1: <HTML>
2: <HEAD>
2.78 frystyk 3: <TITLE>W3C Sample Code Library libwww General Purpose Macros</TITLE>
2.6 timbl 4: </HEAD>
2.3 timbl 5: <BODY>
2.69 frystyk 6: <H1>
7: General Purpose Macros
8: </H1>
2.24 frystyk 9: <PRE>
10: /*
2.31 frystyk 11: ** (c) COPYRIGHT MIT 1995.
2.24 frystyk 12: ** Please first read the full copyright statement in the file COPYRIGH.
13: */
14: </PRE>
2.69 frystyk 15: <P>
2.83 frystyk 16: This module is a part of the <A HREF="http://www.w3.org/Library/">
2.78 frystyk 17: W3C Sample Code Library</A>. See also the system dependent file
2.82 frystyk 18: <A HREF="wwwsys.html">sysdep module</A> for system specific information.
2.1 timbl 19: <PRE>
20: #ifndef HTUTILS_H
21: #define HTUTILS_H
2.56 frystyk 22: </PRE>
2.69 frystyk 23: <H2>
2.71 frystyk 24: <A NAME="Debug">Debug Message Control</A>
2.69 frystyk 25: </H2>
26: <P>
27: This is the global flag for setting the <CODE>WWWTRACE</CODE> options. The
28: verbose mode is no longer a simple boolean but a bit field so that it is
29: possible to see parts of the output messages.
2.20 frystyk 30: <PRE>
2.26 frystyk 31: #ifndef DEBUG
32: #define DEBUG /* No one ever turns this off as trace is too important */
2.81 frystyk 33:
34: /* Call this function and the program halts */
35: extern void HTDebugBreak (char * file, unsigned long line, const char * fmt, ...);
2.56 frystyk 36: #endif
37: </PRE>
2.69 frystyk 38: <H3>
39: Definition of the Global Trace Flag
40: </H3>
41: <P>
2.56 frystyk 42: The global trace flag variable is available everywhere.
43: <PRE>
44: #ifdef DEBUG
2.44 frystyk 45: #ifdef WWW_WIN_DLL
2.56 frystyk 46: extern int * WWW_TraceFlag; /* In DLLs, we need the indirection */
47: #define WWWTRACE (*WWW_TraceFlag)
2.44 frystyk 48: #else
2.85 frystyk 49: extern unsigned int WWW_TraceFlag; /* Global flag for all W3 trace */
2.56 frystyk 50: #define WWWTRACE (WWW_TraceFlag)
51: #endif /* WWW_WIN_DLL */
52: #else
53: #define WWWTRACE 0
54: #endif /* DEBUG */
2.20 frystyk 55: </PRE>
2.69 frystyk 56: <P>
57: The <EM><CODE>WWWTRACE</CODE></EM> define outputs messages if verbose mode
58: is active according to the following rules:
2.20 frystyk 59: <PRE>
2.56 frystyk 60: typedef enum _HTTraceFlags {
2.76 frystyk 61: SHOW_UTIL_TRACE = 0x1,
62: SHOW_APP_TRACE = 0x2,
63: SHOW_CACHE_TRACE = 0x4,
64: SHOW_SGML_TRACE = 0x8,
65: SHOW_BIND_TRACE = 0x10,
66: SHOW_THREAD_TRACE = 0x20,
67: SHOW_STREAM_TRACE = 0x40,
68: SHOW_PROTOCOL_TRACE = 0x80,
69: SHOW_MEM_TRACE = 0x100,
70: SHOW_URI_TRACE = 0x200,
71: SHOW_AUTH_TRACE = 0x400,
72: SHOW_ANCHOR_TRACE = 0x800,
73: SHOW_PICS_TRACE = 0x1000,
74: SHOW_CORE_TRACE = 0x2000,
75: SHOW_MUX_TRACE = 0x4000,
2.84 frystyk 76: SHOW_SQL_TRACE = 0x8000,
2.76 frystyk 77: SHOW_ALL_TRACE = 0xFFFFFFFF
2.56 frystyk 78: } HTTraceFlags;
79: </PRE>
2.69 frystyk 80: <P>
81: The flags are made so that they can serve as a group flag for correlated
82: trace messages, e.g. showing messages for SGML and HTML at the same time.
83: <PRE>
84: #define UTIL_TRACE (WWWTRACE & SHOW_UTIL_TRACE)
85: #define APP_TRACE (WWWTRACE & SHOW_APP_TRACE)
86: #define CACHE_TRACE (WWWTRACE & SHOW_CACHE_TRACE)
87: #define SGML_TRACE (WWWTRACE & SHOW_SGML_TRACE)
88: #define BIND_TRACE (WWWTRACE & SHOW_BIND_TRACE)
89: #define THD_TRACE (WWWTRACE & SHOW_THREAD_TRACE)
90: #define STREAM_TRACE (WWWTRACE & SHOW_STREAM_TRACE)
91: #define PROT_TRACE (WWWTRACE & SHOW_PROTOCOL_TRACE)
92: #define MEM_TRACE (WWWTRACE & SHOW_MEM_TRACE)
93: #define URI_TRACE (WWWTRACE & SHOW_URI_TRACE)
94: #define AUTH_TRACE (WWWTRACE & SHOW_AUTH_TRACE)
95: #define ANCH_TRACE (WWWTRACE & SHOW_ANCHOR_TRACE)
96: #define PICS_TRACE (WWWTRACE & SHOW_PICS_TRACE)
97: #define CORE_TRACE (WWWTRACE & SHOW_CORE_TRACE)
2.76 frystyk 98: #define MUX_TRACE (WWWTRACE & SHOW_MUX_TRACE)
2.84 frystyk 99: #define SQL_TRACE (WWWTRACE & SHOW_SQL_TRACE)
2.69 frystyk 100: </PRE>
101: <H3>
102: Destination for Trace Messages
103: </H3>
104: <P>
105: You can send trace messages to various destinations depending on the type
106: of your application. By default, on Unix the messages are sent to stderr
107: using fprintf() and if we are on Windows and have a windows applications
108: then register a HTTraceCallback function. This is done with HTTrace_setCallback.
109: It tells HTTrace to call a HTTraceCallback. If your compiler has problems
110: with va_list, then you may forget about registering the callback and instead
111: macro HTTrace as follows: #define HTTrace MyAppSpecificTrace
2.67 hallam 112: <A NAME="HTTrace"></A>
2.59 frystyk 113: <PRE>
2.62 frystyk 114: typedef int HTTraceCallback(const char * fmt, va_list pArgs);
2.59 frystyk 115:
116: extern void HTTrace_setCallback(HTTraceCallback * pCall);
117: extern HTTraceCallback * HTTrace_getCallback(void);
118:
2.62 frystyk 119: extern int HTTrace(const char * fmt, ...);
2.26 frystyk 120: </PRE>
2.76 frystyk 121: <H3>
122: Trace Data Logging
123: </H3>
124: <P>
125: A similare mechanism exists for logging data, except that is adds a
126: data and length argument to the trace call.
127: <PRE>
2.77 eric 128: typedef int HTTraceDataCallback(char * data, size_t len,
129: char * fmt, va_list pArgs);
2.76 frystyk 130:
131: extern void HTTraceData_setCallback(HTTraceDataCallback * pCall);
132: extern HTTraceDataCallback * HTTraceData_getCallback(void);
133:
2.77 eric 134: extern int HTTraceData(char * data, size_t len, char * fmt, ...);
2.76 frystyk 135: </PRE>
136: <H3>
137: Hiding Extraneous Logging Messages
138: </H3>
139: <P>
140: Many of the long logging strings are wrapped with the HTHIDE
141: macro. This is usually defined to pass its parameter to the loggin
142: functions. However, if your application doesn't use the logging, you
143: may define HTHIDE to pass only a 0 to eliminate the strings from the
144: executable image.
145: <PRE>
146: #define HTHIDE(A) A
147: </PRE>
2.69 frystyk 148: <H2>
149: Macros for Function Declarations
150: </H2>
2.26 frystyk 151: <PRE>
152: #define PUBLIC /* Accessible outside this module */
2.1 timbl 153: #define PRIVATE static /* Accessible only within this module */
2.56 frystyk 154: </PRE>
2.69 frystyk 155: <H2>
156: Often used Interger Macros
157: </H2>
158: <H3>
159: Min and Max functions
160: </H3>
2.56 frystyk 161: <PRE>
2.11 timbl 162: #ifndef HTMIN
163: #define HTMIN(a,b) ((a) <= (b) ? (a) : (b))
2.69 frystyk 164: #define HTMAX(a,b) ((a) >= (b) ? (a) : (b))
2.1 timbl 165: #endif
2.26 frystyk 166: </PRE>
2.69 frystyk 167: <H3>
168: Double abs function
169: </H3>
2.56 frystyk 170: <PRE>
171: #ifndef HTDABS
172: #define HTDABS(a) ((a) < 0.0 ? (-(a)) : (a))
173: #endif
174: </PRE>
2.69 frystyk 175: <P>
176: <A NAME="ReturnCodes"></A>
177: <H2>
2.70 frystyk 178: <A NAME="return">Return Codes for Protocol Modules and Streams</A>
2.69 frystyk 179: </H2>
180: <P>
181: Theese are the codes returned from the protocol modules, and the stream modules.
182: Success are (>=0) and failure are (<0)
2.3 timbl 183: <PRE>
2.23 frystyk 184: #define HT_OK 0 /* Generic success */
2.37 frystyk 185: #define HT_ALL 1 /* Used by Net Manager */
186:
2.75 frystyk 187: #define HT_CONTINUE 100 /* Continue an operation */
188: #define HT_UPGRADE 101 /* Switching protocols */
189:
190: #define HT_LOADED 200 /* Everything's OK */
191: #define HT_CREATED 201 /* New object is created */
192: #define HT_ACCEPTED 202 /* Accepted */
193: #define HT_NO_DATA 204 /* OK but no data was loaded */
194: #define HT_RESET_CONTENT 205 /* Reset content */
195: #define HT_PARTIAL_CONTENT 206 /* Partial Content */
196:
197: #define HT_MULTIPLE_CHOICES 300 /* Multiple choices */
198: #define HT_PERM_REDIRECT 301 /* Permanent redirection */
2.79 frystyk 199: #define HT_FOUND 302 /* Found */
2.75 frystyk 200: #define HT_SEE_OTHER 303 /* See other */
201: #define HT_NOT_MODIFIED 304 /* Not Modified */
202: #define HT_USE_PROXY 305 /* Use Proxy */
2.79 frystyk 203: #define HT_PROXY_REDIRECT 306 /* Proxy Redirect */
204: #define HT_TEMP_REDIRECT 307 /* Temporary redirect */
2.75 frystyk 205:
206: #define HT_IGNORE 900 /* Ignore this in the Net manager */
207: #define HT_CLOSED 901 /* The socket was closed */
208: #define HT_PENDING 902 /* Wait for connection */
209: #define HT_RELOAD 903 /* If we must reload the document */
2.23 frystyk 210:
211: #define HT_ERROR -1 /* Generic failure */
2.53 frystyk 212:
2.75 frystyk 213: #define HT_NO_ACCESS -401 /* Unauthorized */
214: #define HT_FORBIDDEN -403 /* Access forbidden */
2.87 frystyk 215: #define HT_NOT_FOUND -404 /* Not found */
2.75 frystyk 216: #define HT_NOT_ACCEPTABLE -406 /* Not Acceptable */
217: #define HT_NO_PROXY_ACCESS -407 /* Proxy Authentication Failed */
218: #define HT_CONFLICT -409 /* Conflict */
219: #define HT_LENGTH_REQUIRED -411 /* Length required */
2.79 frystyk 220: #define HT_PRECONDITION_FAILED -412 /* Precondition failed */
221: #define HT_TOO_BIG -413 /* Request entity too large */
222: #define HT_URI_TOO_BIG -414 /* Request-URI too long */
223: #define HT_UNSUPPORTED -415 /* Unsupported */
224: #define HT_BAD_RANGE -416 /* Request Range not satisfiable */
225: #define HT_EXPECTATION_FAILED -417 /* Expectation Failed */
226: #define HT_REAUTH -418 /* Reauthentication required */
227: #define HT_PROXY_REAUTH -419 /* Proxy Reauthentication required */
2.75 frystyk 228:
229: #define HT_RETRY -503 /* If service isn't available */
230: #define HT_BAD_VERSION -505 /* Bad protocol version */
231:
232: #define HT_INTERNAL -900 /* Weird -- should never happen. */
233: #define HT_WOULD_BLOCK -901 /* If we are in a select */
234: #define HT_INTERRUPTED -902 /* Note the negative value! */
235: #define HT_PAUSE -903 /* If we want to pause a stream */
236: #define HT_RECOVER_PIPE -904 /* Recover pipe line */
2.86 frystyk 237: #define HT_TIMEOUT -905 /* Connection timeout */
2.88 ! frystyk 238: #define HT_NO_HOST -906 /* Can't locate host */
2.35 frystyk 239: </PRE>
2.69 frystyk 240: <H2>
241: Upper- and Lowercase macros
242: </H2>
243: <P>
244: The problem here is that toupper(x) is not defined officially unless isupper(x)
245: is. These macros are CERTAINLY needed on #if defined(pyr) || define(mips)
246: or BDSI platforms. For safefy, we make them mandatory.
2.25 roeber 247: <PRE>
2.1 timbl 248: #ifndef TOLOWER
2.27 frystyk 249: #define TOLOWER(c) tolower(c)
250: #define TOUPPER(c) toupper(c)
2.29 frystyk 251: #endif
252: </PRE>
2.69 frystyk 253: <H2>
2.81 frystyk 254: C Preprocessor defines
255: </H2>
256:
257: Make sure that the following macros are defined
258:
259: <PRE>
260: #ifndef __FILE__
261: #define __FILE__ ""
262: #endif
263:
264: #ifndef __LINE__
265: #define __LINE__ 0L
266: #endif
267: </PRE>
268:
269: <H2>
2.69 frystyk 270: Max and Min values for Integers and Floating Point
271: </H2>
2.29 frystyk 272: <PRE>
273: #ifdef FLT_EPSILON /* The ANSI C way define */
274: #define HT_EPSILON FLT_EPSILON
275: #else
276: #define HT_EPSILON 0.00000001
2.27 frystyk 277: #endif
278: </PRE>
2.69 frystyk 279: <H2>
280: The local equivalents of CR and LF
281: </H2>
282: <P>
283: We can check for these after net ascii text has been converted to the local
284: representation. Similarly, we include them in strings to be sent as net ascii
285: after translation.
2.26 frystyk 286: <PRE>
287: #define LF FROMASCII('\012') /* ASCII line feed LOCAL EQUIVALENT */
288: #define CR FROMASCII('\015') /* Will be converted to ^M for transmission */
2.54 frystyk 289: </PRE>
2.69 frystyk 290: <H2>
291: Library Dynamic Memory Magement
292: </H2>
293: <P>
294: The Library has it's own dynamic memory API which is declared in
295: <A HREF="HTMemory.html">memory management module</A>.
2.54 frystyk 296: <PRE>
2.55 frystyk 297: #include "HTMemory.h"
2.26 frystyk 298: </PRE>
2.56 frystyk 299: <PRE>
300: #endif /* HT_UTILS.h */
301: </PRE>
2.69 frystyk 302: <P>
303: <HR>
2.68 frystyk 304: <ADDRESS>
2.88 ! frystyk 305: @(#) $Id: HTUtils.html,v 2.87 1998/11/15 02:04:07 frystyk Exp $
2.68 frystyk 306: </ADDRESS>
2.69 frystyk 307: </BODY></HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTUtils.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src