Annotation of libwww/Library/src/HTUtils.html, revision 2.62
2.6 timbl 1: <HTML>
2: <HEAD>
2.35 frystyk 3: <TITLE>Utility macros</TITLE>
2.62 ! frystyk 4: <!-- Changed by: Henrik Frystyk Nielsen, 29-Feb-1996 -->
2.6 timbl 5: </HEAD>
2.3 timbl 6: <BODY>
2.24 frystyk 7:
2.56 frystyk 8: <H1>General Purpose Macros</H1>
2.20 frystyk 9:
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>
16:
17: This module is a part of the <A
2.44 frystyk 18: HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference Library</A>.
2.20 frystyk 19:
2.62 ! frystyk 20: See also the system dependent file <A HREF="sysdep.html">tcp module</A>
2.26 frystyk 21: for system specific information. <P>
22:
2.1 timbl 23: <PRE>
24: #ifndef HTUTILS_H
25: #define HTUTILS_H
2.56 frystyk 26: </PRE>
27:
28: <A NAME="debug"><H2>Debug Message Control</H2></A>
2.20 frystyk 29:
2.56 frystyk 30: This is the global flag for setting the WWWTRACE options. The verbose
31: mode is no longer a simple boolean but a bit field so that it is
32: possible to see parts of the output messages.
2.20 frystyk 33:
34: <PRE>
2.26 frystyk 35: #ifndef DEBUG
36: #define DEBUG /* No one ever turns this off as trace is too important */
2.56 frystyk 37: #endif
38: </PRE>
39:
40: <H3>Definition of the Global Trace Flag</H3>
2.26 frystyk 41:
2.56 frystyk 42: The global trace flag variable is available everywhere.
43:
44: <PRE>
45: #ifdef DEBUG
2.44 frystyk 46: #ifdef WWW_WIN_DLL
2.56 frystyk 47: extern int * WWW_TraceFlag; /* In DLLs, we need the indirection */
48: #define WWWTRACE (*WWW_TraceFlag)
2.44 frystyk 49: #else
2.56 frystyk 50: extern int WWW_TraceFlag; /* Global flag for all W3 trace */
51: #define WWWTRACE (WWW_TraceFlag)
52: #endif /* WWW_WIN_DLL */
53: #else
54: #define WWWTRACE 0
55: #endif /* DEBUG */
2.20 frystyk 56: </PRE>
57:
2.56 frystyk 58: The <EM>WWWTRACE</EM> define outputs messages if verbose mode is
59: active according to the following rules:
2.1 timbl 60:
2.20 frystyk 61: <PRE>
2.56 frystyk 62: typedef enum _HTTraceFlags {
63: SHOW_UTIL_TRACE = 0x1, /* 1 */
64: SHOW_APP_TRACE = 0x2, /* 10 */
65: SHOW_CACHE_TRACE = 0x4, /* 100 */
66: SHOW_SGML_TRACE = 0x8, /* 1000 */
67: SHOW_BIND_TRACE = 0x10, /* 1.0000 */
68: SHOW_THREAD_TRACE = 0x20, /* 10.0000 */
69: SHOW_STREAM_TRACE = 0x40, /* 100.0000 */
70: SHOW_PROTOCOL_TRACE = 0x80, /* 1000.0000 */
2.57 frystyk 71: SHOW_MEM_TRACE = 0x100, /* 1.0000.0000 */
2.56 frystyk 72: SHOW_URI_TRACE = 0x200, /* 10.0000.0000 */
2.61 frystyk 73: SHOW_AUTH_TRACE = 0x400, /* 1.00.0000.0000 */
2.56 frystyk 74: SHOW_ANCHOR_TRACE = 0x800, /* 10.00.0000.0000 */
75: SHOW_ALL_TRACE = 0xFFF /* 11.11.1111.1111 */
76: } HTTraceFlags;
77: </PRE>
78:
79: The flags are made so that they can serve as a group flag for
80: correlated trace messages, e.g. showing messages for SGML and HTML at
81: the same time.
82:
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)
2.57 frystyk 92: #define MEM_TRACE (WWWTRACE & SHOW_MEM_TRACE)
2.56 frystyk 93: #define URI_TRACE (WWWTRACE & SHOW_URI_TRACE)
2.61 frystyk 94: #define AUTH_TRACE (WWWTRACE & SHOW_AUTH_TRACE)
2.56 frystyk 95: #define ANCH_TRACE (WWWTRACE & SHOW_ANCHOR_TRACE)
96: </PRE>
97:
2.59 frystyk 98: <H3>Destination for Trace Messages</H3>
99:
100: You can send trace messages to various destinations depending on the
101: type of your application. By default, on Unix the messages are sent to
102: stderr using fprintf() and if we are on Windows and have a windows
103: applications then register a HTTraceCallback function. This is done with
104: HTTrace_setCallback. It tells HTTrace to call a HTTraceCallback. If your
105: compiler has problems with va_list, then you may forget about registering
106: the callback and instead macro HTTrace as follows:
107: #define HTTrace MyAppSpecificTrace
108:
109: <PRE>
2.62 ! frystyk 110: typedef int HTTraceCallback(const char * fmt, va_list pArgs);
2.59 frystyk 111:
112: extern void HTTrace_setCallback(HTTraceCallback * pCall);
113: extern HTTraceCallback * HTTrace_getCallback(void);
114:
2.62 ! frystyk 115: extern int HTTrace(const char * fmt, ...);
2.26 frystyk 116: </PRE>
117:
2.56 frystyk 118: <A NAME="declaration"><H2>Macros for Function Declarations</H2></A>
2.26 frystyk 119:
120: <PRE>
121: #define PUBLIC /* Accessible outside this module */
2.1 timbl 122: #define PRIVATE static /* Accessible only within this module */
2.56 frystyk 123: </PRE>
124:
2.3 timbl 125: <H2>Booleans</H2>
2.26 frystyk 126:
127: <PRE>
2.62 ! frystyk 128: #ifndef BOOLEAN
2.26 frystyk 129: typedef char BOOLEAN; /* Logical value */
2.30 frystyk 130: #endif
2.1 timbl 131:
132: #ifndef CURSES
133: #ifndef TRUE
134: #define TRUE (BOOLEAN)1
135: #define FALSE (BOOLEAN)0
136: #endif
2.3 timbl 137: #endif /* CURSES */
2.1 timbl 138:
139: #ifndef BOOL
140: #define BOOL BOOLEAN
141: #endif
2.62 ! frystyk 142:
2.1 timbl 143: #ifndef YES
2.14 timbl 144: #define YES (BOOL)1
145: #define NO (BOOL)0
2.1 timbl 146: #endif
2.56 frystyk 147: </PRE>
148:
149: <H2>NULL Definition</H2>
150:
151: <PRE>
152: #ifndef NULL
153: #define NULL ((void *)0)
154: #endif
155: </PRE>
156:
157: <H2>Often used Interger Macros</H2>
2.1 timbl 158:
2.56 frystyk 159: <H3>Min and Max functions</H3>
160:
161: <PRE>
2.11 timbl 162: #ifndef HTMIN
163: #define HTMIN(a,b) ((a) <= (b) ? (a) : (b))
164: #define HTMAX(a,b) ((a) >= (b) ? (a) : (b))
2.1 timbl 165: #endif
2.26 frystyk 166: </PRE>
2.1 timbl 167:
2.56 frystyk 168: <H3>Double abs function</H3>
169:
170: <PRE>
171: #ifndef HTDABS
172: #define HTDABS(a) ((a) < 0.0 ? (-(a)) : (a))
173: #endif
174: </PRE>
175:
2.35 frystyk 176: <A NAME="ReturnCodes"><H2>Return Codes for Protocol Modules and Streams</H2></A>
177:
178: Theese are the codes returned from the protocol modules, and the
179: stream modules. Success are (>=0) and failure are (<0)
2.1 timbl 180:
2.3 timbl 181: <PRE>
2.23 frystyk 182: #define HT_OK 0 /* Generic success */
2.37 frystyk 183: #define HT_ALL 1 /* Used by Net Manager */
184:
2.53 frystyk 185: #define HT_CLOSED 29992 /* The socket was closed */
2.52 frystyk 186: #define HT_PERSISTENT 29993 /* Wait for persistent connection */
187: #define HT_IGNORE 29994 /* Ignore this in the Net manager */
188: #define HT_NO_DATA 29995 /* OK but no data was loaded */
2.53 frystyk 189: #define HT_RELOAD 29996 /* If we must reload the document */
2.52 frystyk 190: #define HT_PERM_REDIRECT 29997 /* Redo the retrieve with a new URL */
191: #define HT_TEMP_REDIRECT 29998 /* Redo the retrieve with a new URL */
2.23 frystyk 192: #define HT_LOADED 29999 /* Instead of a socket */
193:
194: #define HT_ERROR -1 /* Generic failure */
2.53 frystyk 195:
2.23 frystyk 196: #define HT_NO_ACCESS -10 /* Access not available */
197: #define HT_FORBIDDEN -11 /* Access forbidden */
2.53 frystyk 198: #define HT_RETRY -13 /* If service isn't available */
199:
200: #define HT_INTERNAL -100 /* Weird -- should never happen. */
2.35 frystyk 201:
2.23 frystyk 202: #define HT_WOULD_BLOCK -29997 /* If we are in a select */
2.15 frystyk 203: #define HT_INTERRUPTED -29998 /* Note the negative value! */
2.53 frystyk 204: #define HT_PAUSE -29999 /* If we want to pause a stream */
2.35 frystyk 205: </PRE>
206:
2.26 frystyk 207: <H2>Upper- and Lowercase macros</H2>
208:
209: The problem here is that toupper(x) is not defined officially unless
210: isupper(x) is. These macros are CERTAINLY needed on #if defined(pyr)
211: || define(mips) or BDSI platforms. For safefy, we make them mandatory.
2.1 timbl 212:
2.25 roeber 213: <PRE>
2.1 timbl 214: #ifndef TOLOWER
2.27 frystyk 215: #define TOLOWER(c) tolower(c)
216: #define TOUPPER(c) toupper(c)
2.29 frystyk 217: #endif
218: </PRE>
219:
220: <H2>Max and Min values for Integers and Floating Point</H2>
221:
222: <PRE>
223: #ifdef FLT_EPSILON /* The ANSI C way define */
224: #define HT_EPSILON FLT_EPSILON
225: #else
226: #define HT_EPSILON 0.00000001
2.27 frystyk 227: #endif
228: </PRE>
229:
230: <H2>White Characters</H2>
231:
232: Is character <B>c</B> white space?
233:
234: <PRE>
235: #define WHITE(c) isspace(c)
2.26 frystyk 236: </PRE>
237:
238: <H2>The local equivalents of CR and LF</H2>
2.1 timbl 239:
2.26 frystyk 240: We can check for these after net ascii text has been converted to the
241: local representation. Similarly, we include them in strings to be sent
242: as net ascii after translation.
243:
244: <PRE>
245: #define LF FROMASCII('\012') /* ASCII line feed LOCAL EQUIVALENT */
246: #define CR FROMASCII('\015') /* Will be converted to ^M for transmission */
2.54 frystyk 247: </PRE>
248:
249: <H2>Library Dynamic Memory Magement</H2>
250:
251: The Library has it's own dynamic memory API which is declared in <A
252: HREF="HTMemory.html">memory management module</A>.
253:
254: <PRE>
2.55 frystyk 255: #include "HTMemory.h"
2.26 frystyk 256: </PRE>
2.1 timbl 257:
2.56 frystyk 258: <PRE>
259: #endif /* HT_UTILS.h */
260: </PRE>
261:
262: End of utility declarations
2.26 frystyk 263: </BODY>
2.6 timbl 264: </HTML>
Webmaster