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