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