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