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