Annotation of libwww/Library/src/HTUtils.html, revision 2.75.2.2
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>
2.71 frystyk 25: <A NAME="Debug">Debug Message Control</A>
2.69 frystyk 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.75.2.1 eric 34: extern void HTDebugBreak(void);
2.56 frystyk 35: #endif
36: </PRE>
2.69 frystyk 37: <H3>
38: Definition of the Global Trace Flag
39: </H3>
40: <P>
2.56 frystyk 41: The global trace flag variable is available everywhere.
42: <PRE>
43: #ifdef DEBUG
2.44 frystyk 44: #ifdef WWW_WIN_DLL
2.56 frystyk 45: extern int * WWW_TraceFlag; /* In DLLs, we need the indirection */
46: #define WWWTRACE (*WWW_TraceFlag)
2.44 frystyk 47: #else
2.56 frystyk 48: extern int WWW_TraceFlag; /* Global flag for all W3 trace */
49: #define WWWTRACE (WWW_TraceFlag)
50: #endif /* WWW_WIN_DLL */
51: #else
52: #define WWWTRACE 0
53: #endif /* DEBUG */
2.20 frystyk 54: </PRE>
2.69 frystyk 55: <P>
56: The <EM><CODE>WWWTRACE</CODE></EM> define outputs messages if verbose mode
57: is active according to the following rules:
2.20 frystyk 58: <PRE>
2.56 frystyk 59: typedef enum _HTTraceFlags {
2.75.2.2! frystyk 60: SHOW_UTIL_TRACE = 0x1,
! 61: SHOW_APP_TRACE = 0x2,
! 62: SHOW_CACHE_TRACE = 0x4,
! 63: SHOW_SGML_TRACE = 0x8,
! 64: SHOW_BIND_TRACE = 0x10,
! 65: SHOW_THREAD_TRACE = 0x20,
! 66: SHOW_STREAM_TRACE = 0x40,
! 67: SHOW_PROTOCOL_TRACE = 0x80,
! 68: SHOW_MEM_TRACE = 0x100,
! 69: SHOW_URI_TRACE = 0x200,
! 70: SHOW_AUTH_TRACE = 0x400,
! 71: SHOW_ANCHOR_TRACE = 0x800,
! 72: SHOW_PICS_TRACE = 0x1000,
! 73: SHOW_CORE_TRACE = 0x2000,
! 74: SHOW_MUX_TRACE = 0x4000,
! 75: SHOW_ALL_TRACE = 0xFFFFFFFF
2.56 frystyk 76: } HTTraceFlags;
77: </PRE>
2.69 frystyk 78: <P>
79: The flags are made so that they can serve as a group flag for correlated
80: trace messages, e.g. showing messages for SGML and HTML at the same time.
81: <PRE>
82: #define UTIL_TRACE (WWWTRACE & SHOW_UTIL_TRACE)
83: #define APP_TRACE (WWWTRACE & SHOW_APP_TRACE)
84: #define CACHE_TRACE (WWWTRACE & SHOW_CACHE_TRACE)
85: #define SGML_TRACE (WWWTRACE & SHOW_SGML_TRACE)
86: #define BIND_TRACE (WWWTRACE & SHOW_BIND_TRACE)
87: #define THD_TRACE (WWWTRACE & SHOW_THREAD_TRACE)
88: #define STREAM_TRACE (WWWTRACE & SHOW_STREAM_TRACE)
89: #define PROT_TRACE (WWWTRACE & SHOW_PROTOCOL_TRACE)
90: #define MEM_TRACE (WWWTRACE & SHOW_MEM_TRACE)
91: #define URI_TRACE (WWWTRACE & SHOW_URI_TRACE)
92: #define AUTH_TRACE (WWWTRACE & SHOW_AUTH_TRACE)
93: #define ANCH_TRACE (WWWTRACE & SHOW_ANCHOR_TRACE)
94: #define PICS_TRACE (WWWTRACE & SHOW_PICS_TRACE)
95: #define CORE_TRACE (WWWTRACE & SHOW_CORE_TRACE)
2.75.2.2! frystyk 96: #define MUX_TRACE (WWWTRACE & SHOW_MUX_TRACE)
2.69 frystyk 97: </PRE>
98: <H3>
99: Destination for Trace Messages
100: </H3>
101: <P>
102: You can send trace messages to various destinations depending on the type
103: of your application. By default, on Unix the messages are sent to stderr
104: using fprintf() and if we are on Windows and have a windows applications
105: then register a HTTraceCallback function. This is done with HTTrace_setCallback.
106: It tells HTTrace to call a HTTraceCallback. If your compiler has problems
107: with va_list, then you may forget about registering the callback and instead
108: macro HTTrace as follows: #define HTTrace MyAppSpecificTrace
2.67 hallam 109: <A NAME="HTTrace"></A>
2.59 frystyk 110: <PRE>
2.62 frystyk 111: typedef int HTTraceCallback(const char * fmt, va_list pArgs);
2.59 frystyk 112:
113: extern void HTTrace_setCallback(HTTraceCallback * pCall);
114: extern HTTraceCallback * HTTrace_getCallback(void);
115:
2.62 frystyk 116: extern int HTTrace(const char * fmt, ...);
2.26 frystyk 117: </PRE>
2.69 frystyk 118: <H2>
119: Macros for Function Declarations
120: </H2>
2.26 frystyk 121: <PRE>
122: #define PUBLIC /* Accessible outside this module */
2.1 timbl 123: #define PRIVATE static /* Accessible only within this module */
2.56 frystyk 124: </PRE>
2.69 frystyk 125: <H2>
126: Often used Interger Macros
127: </H2>
128: <H3>
129: Min and Max functions
130: </H3>
2.56 frystyk 131: <PRE>
2.11 timbl 132: #ifndef HTMIN
133: #define HTMIN(a,b) ((a) <= (b) ? (a) : (b))
2.69 frystyk 134: #define HTMAX(a,b) ((a) >= (b) ? (a) : (b))
2.1 timbl 135: #endif
2.26 frystyk 136: </PRE>
2.69 frystyk 137: <H3>
138: Double abs function
139: </H3>
2.56 frystyk 140: <PRE>
141: #ifndef HTDABS
142: #define HTDABS(a) ((a) < 0.0 ? (-(a)) : (a))
143: #endif
144: </PRE>
2.69 frystyk 145: <P>
146: <A NAME="ReturnCodes"></A>
147: <H2>
2.70 frystyk 148: <A NAME="return">Return Codes for Protocol Modules and Streams</A>
2.69 frystyk 149: </H2>
150: <P>
151: Theese are the codes returned from the protocol modules, and the stream modules.
152: Success are (>=0) and failure are (<0)
2.3 timbl 153: <PRE>
2.23 frystyk 154: #define HT_OK 0 /* Generic success */
2.37 frystyk 155: #define HT_ALL 1 /* Used by Net Manager */
156:
2.75 frystyk 157: #define HT_CONTINUE 100 /* Continue an operation */
158: #define HT_UPGRADE 101 /* Switching protocols */
159:
160: #define HT_LOADED 200 /* Everything's OK */
161: #define HT_CREATED 201 /* New object is created */
162: #define HT_ACCEPTED 202 /* Accepted */
163: #define HT_NO_DATA 204 /* OK but no data was loaded */
164: #define HT_RESET_CONTENT 205 /* Reset content */
165: #define HT_PARTIAL_CONTENT 206 /* Partial Content */
166:
167: #define HT_MULTIPLE_CHOICES 300 /* Multiple choices */
168: #define HT_PERM_REDIRECT 301 /* Permanent redirection */
169: #define HT_TEMP_REDIRECT 302 /* Temporary redirection */
170: #define HT_SEE_OTHER 303 /* See other */
171: #define HT_NOT_MODIFIED 304 /* Not Modified */
172: #define HT_USE_PROXY 305 /* Use Proxy */
173:
174: #define HT_IGNORE 900 /* Ignore this in the Net manager */
175: #define HT_CLOSED 901 /* The socket was closed */
176: #define HT_PENDING 902 /* Wait for connection */
177: #define HT_RELOAD 903 /* If we must reload the document */
2.23 frystyk 178:
179: #define HT_ERROR -1 /* Generic failure */
2.53 frystyk 180:
2.75 frystyk 181: #define HT_NO_ACCESS -401 /* Unauthorized */
182: #define HT_FORBIDDEN -403 /* Access forbidden */
183: #define HT_NOT_ACCEPTABLE -406 /* Not Acceptable */
184: #define HT_NO_PROXY_ACCESS -407 /* Proxy Authentication Failed */
185: #define HT_CONFLICT -409 /* Conflict */
186: #define HT_LENGTH_REQUIRED -411 /* Length required */
187:
188: #define HT_RETRY -503 /* If service isn't available */
189: #define HT_BAD_VERSION -505 /* Bad protocol version */
190:
191: #define HT_INTERNAL -900 /* Weird -- should never happen. */
192: #define HT_WOULD_BLOCK -901 /* If we are in a select */
193: #define HT_INTERRUPTED -902 /* Note the negative value! */
194: #define HT_PAUSE -903 /* If we want to pause a stream */
195: #define HT_RECOVER_PIPE -904 /* Recover pipe line */
2.35 frystyk 196: </PRE>
2.69 frystyk 197: <H2>
198: Upper- and Lowercase macros
199: </H2>
200: <P>
201: The problem here is that toupper(x) is not defined officially unless isupper(x)
202: is. These macros are CERTAINLY needed on #if defined(pyr) || define(mips)
203: or BDSI platforms. For safefy, we make them mandatory.
2.25 roeber 204: <PRE>
2.1 timbl 205: #ifndef TOLOWER
2.27 frystyk 206: #define TOLOWER(c) tolower(c)
207: #define TOUPPER(c) toupper(c)
2.29 frystyk 208: #endif
209: </PRE>
2.69 frystyk 210: <H2>
211: Max and Min values for Integers and Floating Point
212: </H2>
2.29 frystyk 213: <PRE>
214: #ifdef FLT_EPSILON /* The ANSI C way define */
215: #define HT_EPSILON FLT_EPSILON
216: #else
217: #define HT_EPSILON 0.00000001
2.27 frystyk 218: #endif
219: </PRE>
2.69 frystyk 220: <H2>
221: White Characters
222: </H2>
223: <P>
2.27 frystyk 224: Is character <B>c</B> white space?
225: <PRE>
226: #define WHITE(c) isspace(c)
2.26 frystyk 227: </PRE>
2.69 frystyk 228: <H2>
229: The local equivalents of CR and LF
230: </H2>
231: <P>
232: We can check for these after net ascii text has been converted to the local
233: representation. Similarly, we include them in strings to be sent as net ascii
234: after translation.
2.26 frystyk 235: <PRE>
236: #define LF FROMASCII('\012') /* ASCII line feed LOCAL EQUIVALENT */
237: #define CR FROMASCII('\015') /* Will be converted to ^M for transmission */
2.54 frystyk 238: </PRE>
2.69 frystyk 239: <H2>
240: Library Dynamic Memory Magement
241: </H2>
242: <P>
243: The Library has it's own dynamic memory API which is declared in
244: <A HREF="HTMemory.html">memory management module</A>.
2.54 frystyk 245: <PRE>
2.55 frystyk 246: #include "HTMemory.h"
2.26 frystyk 247: </PRE>
2.56 frystyk 248: <PRE>
249: #endif /* HT_UTILS.h */
250: </PRE>
2.69 frystyk 251: <P>
252: <HR>
2.68 frystyk 253: <ADDRESS>
2.75.2.2! frystyk 254: @(#) $Id: HTUtils.html,v 2.75.2.1 1996/10/29 21:27:53 eric Exp $
2.68 frystyk 255: </ADDRESS>
2.69 frystyk 256: </BODY></HTML>
Webmaster