Annotation of libwww/Library/src/HTUtils.html, revision 2.93
2.93 ! kirschpi 1: <html>
! 2: <head>
! 3: <meta http-equiv="Content-Type" content="text/html">
! 4: <title>W3C Sample Code Library libwww Debug Information and General Purpose
! 5: Macros</title>
! 6: </head>
! 7:
! 8: <body>
! 9: <h1>Debug Information and General Purpose Macros</h1>
! 10: <pre>/*
2.31 frystyk 11: ** (c) COPYRIGHT MIT 1995.
2.24 frystyk 12: ** Please first read the full copyright statement in the file COPYRIGH.
2.93 ! kirschpi 13: */</pre>
! 14:
! 15: <p>This module is a part of the <a href="http://www.w3.org/Library/"> W3C
! 16: Sample Code Library</a>. See also the system dependent file <a
! 17: href="wwwsys.html">sysdep module</a> for system specific information.</p>
! 18: <pre>#ifndef HTUTILS_H
! 19: #define HTUTILS_H</pre>
! 20:
! 21: <h2>Destination for User Print Messages</h2>
! 22:
! 23: <p>You can send print messages to the user to various destinations depending
! 24: on the type of your application. By default, on Unix the messages are sent to
! 25: <code>stdout</code> using <code>fprintf</code>. If we are on MSWindows and
! 26: have a windows applications then register a <code>HTPrintCallback</code>
! 27: function. This is done with <code>HTPrint_setCallback</code>. It tells
! 28: <code>HTPrint</code> to call a <code>HTPrintCallback</code>. If
! 29: <code>HTDEBUG</code> is not defined then don't do any of the above.</p>
! 30: <pre>typedef int HTPrintCallback(const char * fmt, va_list pArgs);
2.90 frystyk 31: extern void HTPrint_setCallback(HTPrintCallback * pCall);
32: extern HTPrintCallback * HTPrint_getCallback(void);
33:
2.93 ! kirschpi 34: extern int HTPrint(const char * fmt, ...);</pre>
! 35:
! 36: <h2><a name="Debug">Debug Message Control</a></h2>
! 37:
! 38: <p>This is the global flag for setting the <code><em>WWWTRACE</em></code>
! 39: options. The verbose mode is no longer a simple boolean but a bit field so
! 40: that it is possible to see parts of the output messages.</p>
! 41: <pre>#if defined(NODEBUG) || defined(NDEBUG) || defined(_NDEBUG)
2.90 frystyk 42: #undef HTDEBUG
43: #else
44: #ifndef HTDEBUG
45: #define HTDEBUG 1
46: #endif /* HTDEBUG */
2.93 ! kirschpi 47: #endif</pre>
! 48:
! 49: <h3>C Preprocessor defines</h3>
! 50:
! 51: <p>Make sure that the following macros are defined</p>
! 52: <pre>#ifndef __FILE__
2.90 frystyk 53: #define __FILE__ ""
54: #endif
2.81 frystyk 55:
2.90 frystyk 56: #ifndef __LINE__
57: #define __LINE__ 0L
2.93 ! kirschpi 58: #endif</pre>
! 59:
! 60: <h3>Definition of the Global Trace Flag</h3>
! 61:
! 62: <p>The global trace flag variable is available everywhere.</p>
! 63: <pre>#ifdef HTDEBUG
2.44 frystyk 64: #ifdef WWW_WIN_DLL
2.56 frystyk 65: extern int * WWW_TraceFlag; /* In DLLs, we need the indirection */
66: #define WWWTRACE (*WWW_TraceFlag)
2.44 frystyk 67: #else
2.85 frystyk 68: extern unsigned int WWW_TraceFlag; /* Global flag for all W3 trace */
2.56 frystyk 69: #define WWWTRACE (WWW_TraceFlag)
70: #endif /* WWW_WIN_DLL */
71: #else
72: #define WWWTRACE 0
2.93 ! kirschpi 73: #endif /* HTDEBUG */</pre>
! 74:
! 75: <h3>Select which Trace Messages to show</h3>
! 76:
! 77: <p>Libwww has a huge set of trace messages and it is therefor a good idea to
! 78: be able to select which ones to see for any particular trace. An easy way to
! 79: set this is using the funtion <a
! 80: href="HTHome.html#Trace">HTSetTraceMessageMask</a>. The <em>WWWTRACE</em>
2.90 frystyk 81: define outputs messages if verbose mode is active according to the following
2.93 ! kirschpi 82: rules:</p>
! 83: <pre>typedef enum _HTTraceFlags {
2.76 frystyk 84: SHOW_UTIL_TRACE = 0x1,
85: SHOW_APP_TRACE = 0x2,
86: SHOW_CACHE_TRACE = 0x4,
87: SHOW_SGML_TRACE = 0x8,
88: SHOW_BIND_TRACE = 0x10,
89: SHOW_THREAD_TRACE = 0x20,
90: SHOW_STREAM_TRACE = 0x40,
91: SHOW_PROTOCOL_TRACE = 0x80,
92: SHOW_MEM_TRACE = 0x100,
93: SHOW_URI_TRACE = 0x200,
94: SHOW_AUTH_TRACE = 0x400,
95: SHOW_ANCHOR_TRACE = 0x800,
96: SHOW_PICS_TRACE = 0x1000,
97: SHOW_CORE_TRACE = 0x2000,
98: SHOW_MUX_TRACE = 0x4000,
2.84 frystyk 99: SHOW_SQL_TRACE = 0x8000,
2.90 frystyk 100: SHOW_XML_TRACE = 0x10000,
2.92 kahan 101: SHOW_ALL_TRACE = (int) 0xFFFFFFFF
2.93 ! kirschpi 102: } HTTraceFlags;</pre>
! 103:
! 104: <p>The flags are made so that they can serve as a group flag for correlated
! 105: trace messages, e.g. showing messages for SGML and HTML at the same time.</p>
! 106: <pre>#define UTIL_TRACE (WWWTRACE & SHOW_UTIL_TRACE)
2.69 frystyk 107: #define APP_TRACE (WWWTRACE & SHOW_APP_TRACE)
108: #define CACHE_TRACE (WWWTRACE & SHOW_CACHE_TRACE)
109: #define SGML_TRACE (WWWTRACE & SHOW_SGML_TRACE)
110: #define BIND_TRACE (WWWTRACE & SHOW_BIND_TRACE)
111: #define THD_TRACE (WWWTRACE & SHOW_THREAD_TRACE)
112: #define STREAM_TRACE (WWWTRACE & SHOW_STREAM_TRACE)
113: #define PROT_TRACE (WWWTRACE & SHOW_PROTOCOL_TRACE)
114: #define MEM_TRACE (WWWTRACE & SHOW_MEM_TRACE)
115: #define URI_TRACE (WWWTRACE & SHOW_URI_TRACE)
116: #define AUTH_TRACE (WWWTRACE & SHOW_AUTH_TRACE)
117: #define ANCH_TRACE (WWWTRACE & SHOW_ANCHOR_TRACE)
118: #define PICS_TRACE (WWWTRACE & SHOW_PICS_TRACE)
119: #define CORE_TRACE (WWWTRACE & SHOW_CORE_TRACE)
2.76 frystyk 120: #define MUX_TRACE (WWWTRACE & SHOW_MUX_TRACE)
2.84 frystyk 121: #define SQL_TRACE (WWWTRACE & SHOW_SQL_TRACE)
2.90 frystyk 122: #define XML_TRACE (WWWTRACE & SHOW_XML_TRACE)
2.93 ! kirschpi 123: #define ALL_TRACE (WWWTRACE & SHOW_ALL_TRACE)</pre>
! 124:
! 125: <h3>Destination for Trace Messages</h3>
! 126:
! 127: <p>You can send trace messages to various destinations depending on the type
2.90 frystyk 128: of your application. By default, on Unix the messages are sent to
2.93 ! kirschpi 129: <code>stderr</code> using <code>fprintf</code>. If we are on MSWindows and
! 130: have a windows applications then register a <code>HTTraceCallback</code>
! 131: function. This is done with <code>HTTrace_setCallback</code>. It tells
! 132: <code>HTTrace</code> to call a <code>HTTraceCallback</code>. If
! 133: <code>HTDEBUG</code> is not defined then don't do any of the above.</p>
! 134: <pre>typedef int HTTraceCallback(const char * fmt, va_list pArgs);
2.59 frystyk 135: extern void HTTrace_setCallback(HTTraceCallback * pCall);
2.93 ! kirschpi 136: extern HTTraceCallback * HTTrace_getCallback(void);</pre>
! 137:
! 138: <p>The <code>HTTRACE</code> macro uses "<code>_</code>" as parameter
! 139: separater instead of "<code>,</code>". This enables us to use a single macro
! 140: instead of a macro for each number of arguments which we consider a more
! 141: elegant and flexible solution. The implication is, however, that we can't
! 142: have variables that start or end with an "<code>_</code>" if they are to be
! 143: used in a trace message.</p>
! 144: <pre>#ifdef HTDEBUG
2.91 frystyk 145: #undef _
2.90 frystyk 146: #define _ ,
147: #define HTTRACE(TYPE, FMT) \
148: do { if (TYPE) HTTrace(FMT); } while (0);
2.62 frystyk 149: extern int HTTrace(const char * fmt, ...);
2.90 frystyk 150: #else
151: #define HTTRACE(TYPE, FMT) /* empty */
2.93 ! kirschpi 152: #endif /* HTDEBUG */</pre>
! 153:
! 154: <h3>Data Trace Logging</h3>
! 155:
! 156: <p>A similar mechanism exists for logging data, except that is adds a data
! 157: and length argument to the trace call. Again, you can register your own
! 158: callbacks if need be.</p>
! 159: <pre>typedef int HTTraceDataCallback(char * data, size_t len, char * fmt, va_list pArgs);
2.76 frystyk 160: extern void HTTraceData_setCallback(HTTraceDataCallback * pCall);
2.93 ! kirschpi 161: extern HTTraceDataCallback * HTTraceData_getCallback(void);</pre>
! 162:
! 163: <p>Again we use the same macro expansion mechanism as for
! 164: <code>HTTrace</code></p>
! 165: <pre>#ifdef HTDEBUG
2.90 frystyk 166: #define HTTRACEDATA(DATA, LEN, FMT) HTTraceData((DATA), (LEN), FMT)
2.77 eric 167: extern int HTTraceData(char * data, size_t len, char * fmt, ...);
2.90 frystyk 168: #else
169: #define HTTRACEDATA(DATA, LEN, FMT) /* empty */
2.93 ! kirschpi 170: #endif /* HTDEBUG */</pre>
! 171:
! 172: <h3>Debug Breaks</h3>
! 173:
! 174: <p>Call this function and the program halts. We use the same macro expansion
! 175: mechanism as for <code>HTTrace</code></p>
! 176: <pre>extern void HTDebugBreak(char * file, unsigned long line, const char * fmt, ...);
2.90 frystyk 177:
178: #ifdef HTDEBUG
179: #define HTDEBUGBREAK(FMT) HTDebugBreak(__FILE__, __LINE__, FMT)
180: #else
181: #define HTDEBUGBREAK(FMT) /* empty */
2.93 ! kirschpi 182: #endif /* HTDEBUG */</pre>
! 183:
! 184: <h2>Macros for Function Declarations</h2>
! 185:
! 186: <p>These function prefixes are used by scripts and other tools and helps
! 187: figuring out which functions are exported and which are not. See also the <a
! 188: href="../User/Style/Macros.html">libwww style guide</a>.</p>
! 189: <pre>#define PUBLIC /* Accessible outside this module */
! 190: #define PRIVATE static /* Accessible only within this module */</pre>
! 191:
! 192: <h2>Often used Interger Macros</h2>
! 193:
! 194: <h3>Min and Max functions</h3>
! 195: <pre>#ifndef HTMIN
2.11 timbl 196: #define HTMIN(a,b) ((a) <= (b) ? (a) : (b))
2.69 frystyk 197: #define HTMAX(a,b) ((a) >= (b) ? (a) : (b))
2.93 ! kirschpi 198: #endif</pre>
! 199:
! 200: <h3>Double abs function</h3>
! 201: <pre>#ifndef HTDABS
2.56 frystyk 202: #define HTDABS(a) ((a) < 0.0 ? (-(a)) : (a))
2.93 ! kirschpi 203: #endif</pre>
! 204:
! 205: <p><a name="ReturnCodes"></a></p>
! 206:
! 207: <h2><a name="return">Return Codes for Protocol Modules and Streams</a></h2>
! 208:
! 209: <p>Theese are the codes returned from the protocol modules, and the stream
! 210: modules. Success are (>=0) and failure are (<0)</p>
! 211: <pre>#define HT_OK 0 /* Generic success */
2.37 frystyk 212: #define HT_ALL 1 /* Used by Net Manager */
213:
2.75 frystyk 214: #define HT_CONTINUE 100 /* Continue an operation */
215: #define HT_UPGRADE 101 /* Switching protocols */
216:
217: #define HT_LOADED 200 /* Everything's OK */
218: #define HT_CREATED 201 /* New object is created */
219: #define HT_ACCEPTED 202 /* Accepted */
220: #define HT_NO_DATA 204 /* OK but no data was loaded */
221: #define HT_RESET_CONTENT 205 /* Reset content */
222: #define HT_PARTIAL_CONTENT 206 /* Partial Content */
223:
224: #define HT_MULTIPLE_CHOICES 300 /* Multiple choices */
225: #define HT_PERM_REDIRECT 301 /* Permanent redirection */
2.79 frystyk 226: #define HT_FOUND 302 /* Found */
2.75 frystyk 227: #define HT_SEE_OTHER 303 /* See other */
228: #define HT_NOT_MODIFIED 304 /* Not Modified */
229: #define HT_USE_PROXY 305 /* Use Proxy */
2.79 frystyk 230: #define HT_PROXY_REDIRECT 306 /* Proxy Redirect */
231: #define HT_TEMP_REDIRECT 307 /* Temporary redirect */
2.75 frystyk 232:
233: #define HT_IGNORE 900 /* Ignore this in the Net manager */
234: #define HT_CLOSED 901 /* The socket was closed */
235: #define HT_PENDING 902 /* Wait for connection */
236: #define HT_RELOAD 903 /* If we must reload the document */
2.23 frystyk 237:
238: #define HT_ERROR -1 /* Generic failure */
2.53 frystyk 239:
2.75 frystyk 240: #define HT_NO_ACCESS -401 /* Unauthorized */
241: #define HT_FORBIDDEN -403 /* Access forbidden */
2.87 frystyk 242: #define HT_NOT_FOUND -404 /* Not found */
2.75 frystyk 243: #define HT_NOT_ACCEPTABLE -406 /* Not Acceptable */
244: #define HT_NO_PROXY_ACCESS -407 /* Proxy Authentication Failed */
245: #define HT_CONFLICT -409 /* Conflict */
246: #define HT_LENGTH_REQUIRED -411 /* Length required */
2.79 frystyk 247: #define HT_PRECONDITION_FAILED -412 /* Precondition failed */
248: #define HT_TOO_BIG -413 /* Request entity too large */
249: #define HT_URI_TOO_BIG -414 /* Request-URI too long */
250: #define HT_UNSUPPORTED -415 /* Unsupported */
251: #define HT_BAD_RANGE -416 /* Request Range not satisfiable */
252: #define HT_EXPECTATION_FAILED -417 /* Expectation Failed */
253: #define HT_REAUTH -418 /* Reauthentication required */
254: #define HT_PROXY_REAUTH -419 /* Proxy Reauthentication required */
2.75 frystyk 255:
256: #define HT_RETRY -503 /* If service isn't available */
257: #define HT_BAD_VERSION -505 /* Bad protocol version */
258:
2.93 ! kirschpi 259: #ifdef HT_DAV /* WebDAV Status codes */
! 260: #define HT_PROCESSING 102 /* Processing */
! 261: #define HT_MULTI_STATUS 207 /* Multi-Status */
! 262: #define HT_UNPROCESSABLE -422 /* Unprocessable Entity */
! 263: #define HT_LOCKED -423 /* Locked */
! 264: #define HT_FAILED_DEPENDENCY -424 /* Failed Dependency */
! 265: #define HT_INSUFFICIENT_STORAGE -507 /* Insufficient Storage */
! 266: #endif
! 267:
2.75 frystyk 268: #define HT_INTERNAL -900 /* Weird -- should never happen. */
269: #define HT_WOULD_BLOCK -901 /* If we are in a select */
270: #define HT_INTERRUPTED -902 /* Note the negative value! */
271: #define HT_PAUSE -903 /* If we want to pause a stream */
272: #define HT_RECOVER_PIPE -904 /* Recover pipe line */
2.86 frystyk 273: #define HT_TIMEOUT -905 /* Connection timeout */
2.93 ! kirschpi 274: #define HT_NO_HOST -906 /* Can't locate host */</pre>
! 275:
! 276: <h2>Upper- and Lowercase macros</h2>
! 277:
! 278: <p>The problem here is that toupper(x) is not defined officially unless
! 279: isupper(x) is. These macros are CERTAINLY needed on #if defined(pyr) ||
! 280: define(mips) or BDSI platforms. For safefy, we make them mandatory.</p>
! 281: <pre>#ifndef TOLOWER
2.89 frystyk 282: #define TOLOWER(c) tolower((int) (c))
283: #define TOUPPER(c) toupper((int) (c))
2.93 ! kirschpi 284: #endif</pre>
! 285:
! 286: <h2>Max and Min values for Integers and Floating Point</h2>
! 287: <pre>#ifdef FLT_EPSILON /* The ANSI C way define */
2.29 frystyk 288: #define HT_EPSILON FLT_EPSILON
289: #else
290: #define HT_EPSILON 0.00000001
2.93 ! kirschpi 291: #endif</pre>
! 292:
! 293: <h2>The local equivalents of CR and LF</h2>
! 294:
! 295: <p>We can check for these after net ascii text has been converted to the
! 296: local representation. Similarly, we include them in strings to be sent as net
! 297: ascii after translation.</p>
! 298: <pre>#define LF FROMASCII('\012') /* ASCII line feed LOCAL EQUIVALENT */
! 299: #define CR FROMASCII('\015') /* Will be converted to ^M for transmission */</pre>
! 300:
! 301: <h2>Library Dynamic Memory Magement</h2>
! 302:
! 303: <p>The Library has it's own dynamic memory API which is declared in <a
! 304: href="HTMemory.html">memory management module</a>.</p>
! 305: <pre>#include "HTMemory.h"</pre>
! 306: <pre>#endif /* HT_UTILS.h */</pre>
! 307:
! 308: <p></p>
! 309: <hr>
! 310: <address>
! 311: @(#) $Id: HTUtils.html,v 2.92 2000/01/06 10:48:50 kahan Exp $
! 312: </address>
! 313: </body>
! 314: </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