Annotation of libwww/Library/src/HTUtils.html, revision 2.59
2.6 timbl 1: <HTML>
2: <HEAD>
2.35 frystyk 3: <TITLE>Utility macros</TITLE>
2.58 eric 4: <!-- Changed by: Henrik Frystyk Nielsen, 12-Feb-1996 -->
5: <!-- Changed by: Eric Prud'hommeaux, 13-Feb-1996 -->
2.59 ! frystyk 6: <!-- Changed by: Henrik Frystyk Nielsen, 14-Feb-1996 -->
2.6 timbl 7: </HEAD>
2.3 timbl 8: <BODY>
2.24 frystyk 9:
2.56 frystyk 10: <H1>General Purpose Macros</H1>
2.20 frystyk 11:
2.24 frystyk 12: <PRE>
13: /*
2.31 frystyk 14: ** (c) COPYRIGHT MIT 1995.
2.24 frystyk 15: ** Please first read the full copyright statement in the file COPYRIGH.
16: */
17: </PRE>
18:
19: This module is a part of the <A
2.44 frystyk 20: HREF="http://www.w3.org/pub/WWW/Library/"> W3C Reference Library</A>.
2.20 frystyk 21:
2.26 frystyk 22: See also the system dependent file <A HREF="tcp.html">tcp module</A>
23: for system specific information. <P>
24:
2.1 timbl 25: <PRE>
26: #ifndef HTUTILS_H
27: #define HTUTILS_H
2.56 frystyk 28: </PRE>
29:
30: <H2>Are we using Standard Code?</H2>
2.1 timbl 31:
2.56 frystyk 32: We hopefully are...
33:
34: <PRE>
2.51 frystyk 35: #if defined(__STDC__) || defined(__cplusplus) || defined(WWW_MSWINDOWS)
2.26 frystyk 36: #define _STANDARD_CODE_
2.1 timbl 37: #endif
2.20 frystyk 38: </PRE>
39:
2.59 ! frystyk 40: <H3>Variable Argument Functions</H3>
! 41:
! 42: This is normally one of the more tricky part in portable code as it
! 43: very often doesn't work. If you are going to use it then watch out!
! 44:
! 45: <PRE>
! 46: #ifdef _STANDARD_CODE_
! 47: #include <stdarg.h>
! 48: #else
! 49: #include <varargs.h>
! 50: #endif
! 51: </PRE>
! 52:
2.56 frystyk 53: <A NAME="debug"><H2>Debug Message Control</H2></A>
2.20 frystyk 54:
2.56 frystyk 55: This is the global flag for setting the WWWTRACE options. The verbose
56: mode is no longer a simple boolean but a bit field so that it is
57: possible to see parts of the output messages.
2.20 frystyk 58:
59: <PRE>
2.26 frystyk 60: #ifndef DEBUG
61: #define DEBUG /* No one ever turns this off as trace is too important */
2.56 frystyk 62: #endif
63: </PRE>
64:
65: <H3>Definition of the Global Trace Flag</H3>
2.26 frystyk 66:
2.56 frystyk 67: The global trace flag variable is available everywhere.
68:
69: <PRE>
70: #ifdef DEBUG
2.44 frystyk 71: #ifdef WWW_WIN_DLL
2.56 frystyk 72: extern int * WWW_TraceFlag; /* In DLLs, we need the indirection */
73: #define WWWTRACE (*WWW_TraceFlag)
2.44 frystyk 74: #else
2.56 frystyk 75: extern int WWW_TraceFlag; /* Global flag for all W3 trace */
76: #define WWWTRACE (WWW_TraceFlag)
77: #endif /* WWW_WIN_DLL */
78: #else
79: #define WWWTRACE 0
80: #endif /* DEBUG */
2.20 frystyk 81: </PRE>
82:
2.56 frystyk 83: The <EM>WWWTRACE</EM> define outputs messages if verbose mode is
84: active according to the following rules:
2.1 timbl 85:
2.20 frystyk 86: <PRE>
2.56 frystyk 87: typedef enum _HTTraceFlags {
88: SHOW_UTIL_TRACE = 0x1, /* 1 */
89: SHOW_APP_TRACE = 0x2, /* 10 */
90: SHOW_CACHE_TRACE = 0x4, /* 100 */
91: SHOW_SGML_TRACE = 0x8, /* 1000 */
92: SHOW_BIND_TRACE = 0x10, /* 1.0000 */
93: SHOW_THREAD_TRACE = 0x20, /* 10.0000 */
94: SHOW_STREAM_TRACE = 0x40, /* 100.0000 */
95: SHOW_PROTOCOL_TRACE = 0x80, /* 1000.0000 */
2.57 frystyk 96: SHOW_MEM_TRACE = 0x100, /* 1.0000.0000 */
2.56 frystyk 97: SHOW_URI_TRACE = 0x200, /* 10.0000.0000 */
98: SHOW_ANCHOR_TRACE = 0x800, /* 10.00.0000.0000 */
99: SHOW_ALL_TRACE = 0xFFF /* 11.11.1111.1111 */
100: } HTTraceFlags;
101: </PRE>
102:
103: The flags are made so that they can serve as a group flag for
104: correlated trace messages, e.g. showing messages for SGML and HTML at
105: the same time.
106:
107: <PRE>
108: #define UTIL_TRACE (WWWTRACE & SHOW_UTIL_TRACE)
109: #define APP_TRACE (WWWTRACE & SHOW_APP_TRACE)
110: #define CACHE_TRACE (WWWTRACE & SHOW_CACHE_TRACE)
111: #define SGML_TRACE (WWWTRACE & SHOW_SGML_TRACE)
112: #define BIND_TRACE (WWWTRACE & SHOW_BIND_TRACE)
113: #define THD_TRACE (WWWTRACE & SHOW_THREAD_TRACE)
114: #define STREAM_TRACE (WWWTRACE & SHOW_STREAM_TRACE)
115: #define PROT_TRACE (WWWTRACE & SHOW_PROTOCOL_TRACE)
2.57 frystyk 116: #define MEM_TRACE (WWWTRACE & SHOW_MEM_TRACE)
2.56 frystyk 117: #define URI_TRACE (WWWTRACE & SHOW_URI_TRACE)
118: #define ANCH_TRACE (WWWTRACE & SHOW_ANCHOR_TRACE)
119: </PRE>
120:
2.59 ! frystyk 121: <H3>Destination for Trace Messages</H3>
! 122:
! 123: You can send trace messages to various destinations depending on the
! 124: type of your application. By default, on Unix the messages are sent to
! 125: stderr using fprintf() and if we are on Windows and have a windows
! 126: applications then register a HTTraceCallback function. This is done with
! 127: HTTrace_setCallback. It tells HTTrace to call a HTTraceCallback. If your
! 128: compiler has problems with va_list, then you may forget about registering
! 129: the callback and instead macro HTTrace as follows:
! 130: #define HTTrace MyAppSpecificTrace
! 131:
! 132: <PRE>
! 133: typedef int HTTraceCallback(CONST char * fmt, va_list pArgs);
! 134:
! 135: extern void HTTrace_setCallback(HTTraceCallback * pCall);
! 136: extern HTTraceCallback * HTTrace_getCallback(void);
! 137:
! 138: extern int HTTrace(CONST char * fmt, ...);
! 139: </PRE>
! 140:
2.26 frystyk 141: <H2>Standard C library for malloc() etc</H2>
142:
143: Replace memory allocation and free C RTL functions with VAXC$xxx_OPT
2.56 frystyk 144: alternatives for VAXC (but not DECC) on VMS. This makes a big
145: performance difference. (Foteos Macrides). Also have a look at the <A
146: HREF="HTMemory.html">Dynamic Memory Module</A> for how to handle
147: <CODE>malloc</CODE> and <CODE>calloc</CODE>.
2.26 frystyk 148:
149: <PRE>
150: #ifdef vax
151: #ifdef unix
152: #define ultrix /* Assume vax+unix=ultrix */
153: #endif
154: #endif
155:
156: #ifndef VMS
157: #ifndef ultrix
158: #ifdef NeXT
159: #include <libc.h> /* NeXT */
160: #endif
161:
162: #ifndef Mips
163: #ifndef MACH /* Vincent.Cate@furmint.nectar.cs.cmu.edu */
164: #include <stdlib.h> /* ANSI */
165: #endif
166: #endif
167:
168: #else /* ultrix */
169: #include <malloc.h>
170: #include <memory.h>
171: #include <stdio.h>
172: #include <stdlib.h> /* ANSI */ /* BSN */
173: #endif
174:
175: #else /* VMS */
176: #include <stdio.h>
177: #include <stdlib.h>
178: #include <unixlib.h>
179: #include <ctype.h>
180: #if defined(VAXC) && !defined(__DECC)
181: #define malloc VAXC$MALLOC_OPT
182: #define calloc VAXC$CALLOC_OPT
183: #define free VAXC$FREE_OPT
184: #define cfree VAXC$CFREE_OPT
185: #define realloc VAXC$REALLOC_OPT
186: #endif /* VAXC but not DECC */
187: #define unlink remove
188: #define gmtime localtime
189: #include <stat.h>
190: #define S_ISDIR(m) (((m)&S_IFMT) == S_IFDIR)
191: #define S_ISREG(m) (((m)&S_IFMT) == S_IFREG)
192: #define putenv HTVMS_putenv
193: #endif
194: </PRE>
195:
2.56 frystyk 196: <A NAME="declaration"><H2>Macros for Function Declarations</H2></A>
2.26 frystyk 197:
198: <PRE>
199: #define PUBLIC /* Accessible outside this module */
2.1 timbl 200: #define PRIVATE static /* Accessible only within this module */
201:
2.26 frystyk 202: #ifdef _STANDARD_CODE_
203:
2.49 frystyk 204: #if defined(sco) && !defined(_SCO_DS)
205: #define CONST /* The pre SCO 5.0 CC compiler does not know const */
2.26 frystyk 206: #else
2.49 frystyk 207: #define CONST const /* "const" only exists in STDC */
2.26 frystyk 208: #endif
2.50 frystyk 209:
210: #else
211:
212: #define CONST
2.26 frystyk 213:
2.21 frystyk 214: #endif /* _STANDARD_CODE_ (ANSI) */
2.56 frystyk 215: </PRE>
216:
2.3 timbl 217: <H2>Booleans</H2>
2.26 frystyk 218:
219: <PRE>
2.30 frystyk 220: #ifndef BOOLEAN_DEFINED
2.26 frystyk 221: typedef char BOOLEAN; /* Logical value */
2.30 frystyk 222: #endif
2.1 timbl 223:
224: #ifndef CURSES
225: #ifndef TRUE
226: #define TRUE (BOOLEAN)1
227: #define FALSE (BOOLEAN)0
228: #endif
2.3 timbl 229: #endif /* CURSES */
2.1 timbl 230:
231: #ifndef BOOL
232: #define BOOL BOOLEAN
233: #endif
234: #ifndef YES
2.14 timbl 235: #define YES (BOOL)1
236: #define NO (BOOL)0
2.1 timbl 237: #endif
2.56 frystyk 238: </PRE>
239:
240: <H2>NULL Definition</H2>
241:
242: <PRE>
243: #ifndef NULL
244: #define NULL ((void *)0)
245: #endif
246: </PRE>
247:
248: <H2>Often used Interger Macros</H2>
2.1 timbl 249:
2.56 frystyk 250: <H3>Min and Max functions</H3>
251:
252: <PRE>
2.11 timbl 253: #ifndef HTMIN
254: #define HTMIN(a,b) ((a) <= (b) ? (a) : (b))
255: #define HTMAX(a,b) ((a) >= (b) ? (a) : (b))
2.1 timbl 256: #endif
2.26 frystyk 257: </PRE>
2.1 timbl 258:
2.56 frystyk 259: <H3>Double abs function</H3>
260:
261: <PRE>
262: #ifndef HTDABS
263: #define HTDABS(a) ((a) < 0.0 ? (-(a)) : (a))
264: #endif
265: </PRE>
266:
2.35 frystyk 267: <A NAME="ReturnCodes"><H2>Return Codes for Protocol Modules and Streams</H2></A>
268:
269: Theese are the codes returned from the protocol modules, and the
270: stream modules. Success are (>=0) and failure are (<0)
2.1 timbl 271:
2.3 timbl 272: <PRE>
2.23 frystyk 273: #define HT_OK 0 /* Generic success */
2.37 frystyk 274: #define HT_ALL 1 /* Used by Net Manager */
275:
2.53 frystyk 276: #define HT_CLOSED 29992 /* The socket was closed */
2.52 frystyk 277: #define HT_PERSISTENT 29993 /* Wait for persistent connection */
278: #define HT_IGNORE 29994 /* Ignore this in the Net manager */
279: #define HT_NO_DATA 29995 /* OK but no data was loaded */
2.53 frystyk 280: #define HT_RELOAD 29996 /* If we must reload the document */
2.52 frystyk 281: #define HT_PERM_REDIRECT 29997 /* Redo the retrieve with a new URL */
282: #define HT_TEMP_REDIRECT 29998 /* Redo the retrieve with a new URL */
2.23 frystyk 283: #define HT_LOADED 29999 /* Instead of a socket */
284:
285: #define HT_ERROR -1 /* Generic failure */
2.53 frystyk 286:
2.23 frystyk 287: #define HT_NO_ACCESS -10 /* Access not available */
288: #define HT_FORBIDDEN -11 /* Access forbidden */
2.53 frystyk 289: #define HT_RETRY -13 /* If service isn't available */
290:
291: #define HT_INTERNAL -100 /* Weird -- should never happen. */
2.35 frystyk 292:
2.23 frystyk 293: #define HT_WOULD_BLOCK -29997 /* If we are in a select */
2.15 frystyk 294: #define HT_INTERRUPTED -29998 /* Note the negative value! */
2.53 frystyk 295: #define HT_PAUSE -29999 /* If we want to pause a stream */
2.35 frystyk 296: </PRE>
297:
2.26 frystyk 298: <H2>Upper- and Lowercase macros</H2>
299:
300: The problem here is that toupper(x) is not defined officially unless
301: isupper(x) is. These macros are CERTAINLY needed on #if defined(pyr)
302: || define(mips) or BDSI platforms. For safefy, we make them mandatory.
2.1 timbl 303:
2.25 roeber 304: <PRE>
2.26 frystyk 305: #include <ctype.h>
2.1 timbl 306:
307: #ifndef TOLOWER
2.27 frystyk 308: #define TOLOWER(c) tolower(c)
309: #define TOUPPER(c) toupper(c)
2.29 frystyk 310: #endif
311: </PRE>
312:
313: <H2>Max and Min values for Integers and Floating Point</H2>
314:
315: <PRE>
316: #ifdef FLT_EPSILON /* The ANSI C way define */
317: #define HT_EPSILON FLT_EPSILON
318: #else
319: #define HT_EPSILON 0.00000001
2.27 frystyk 320: #endif
321: </PRE>
322:
323: <H2>White Characters</H2>
324:
325: Is character <B>c</B> white space?
326:
327: <PRE>
328: #define WHITE(c) isspace(c)
2.26 frystyk 329: </PRE>
330:
331: <H2>The local equivalents of CR and LF</H2>
2.1 timbl 332:
2.26 frystyk 333: We can check for these after net ascii text has been converted to the
334: local representation. Similarly, we include them in strings to be sent
335: as net ascii after translation.
336:
337: <PRE>
338: #define LF FROMASCII('\012') /* ASCII line feed LOCAL EQUIVALENT */
339: #define CR FROMASCII('\015') /* Will be converted to ^M for transmission */
2.54 frystyk 340: </PRE>
341:
342: <H2>Library Dynamic Memory Magement</H2>
343:
344: The Library has it's own dynamic memory API which is declared in <A
345: HREF="HTMemory.html">memory management module</A>.
346:
347: <PRE>
2.55 frystyk 348: #include "HTMemory.h"
2.26 frystyk 349: </PRE>
2.1 timbl 350:
2.56 frystyk 351: <PRE>
352: #endif /* HT_UTILS.h */
353: </PRE>
354:
355: End of utility declarations
2.26 frystyk 356: </BODY>
2.6 timbl 357: </HTML>
Webmaster