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