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