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