#include <HttpServer.h>

Include dependency graph for HttpTrace.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	HttpTrace
	Buffered diagnostic output and optional HTTP protocol tracing. More...

struct	HttpTraceWriteLock
	HttpTraceWriteLock is a C++ class that makes it easier to lock the trace by using method HttpTrace::getWriter and HttpTrace::releaseWriter. More...

Macros
#define	HttpTrace_isRequestSet() (HttpTrace_getTraceCmds() & HttpTrace_doRequestMask ? TRUE : FALSE)

#define	HttpTrace_isRequestHeadersSet() (HttpTrace_getTraceCmds() & HttpTrace_doRequestHeadersMask ? TRUE : FALSE)

#define	HttpTrace_isResponseHeadersSet() (HttpTrace_getTraceCmds() & HttpTrace_doResponseHeadersMask ? TRUE : FALSE)

#define	HttpTrace_isResponseBodySet() (HttpTrace_getTraceCmds() & HttpTrace_doResponseBodyMask ? TRUE : FALSE)

#define	HttpTrace_isHttp11StateSet() (HttpTrace_getTraceCmds() & HttpTrace_doHttp11StateMask ? TRUE : FALSE)

Typedefs
typedef void(*	HttpTrace_Flush) (char *buf, int bufLen)
	Consume buffered trace output synchronously. More...

typedef struct HttpTrace	HttpTrace
	Buffered diagnostic output and optional HTTP protocol tracing. More...

Functions
BA_API int	HttpTrace_setPrio (int prio)
	Set the trace message priority filter. More...

BA_API void	HttpTrace_setFLushCallback (HttpTrace_Flush fcb)
	The HTTP_TRACE compile time macro adds the trace library to the Barracuda library, but the trace functions will have no effect if you do not provide a callback function. More...

BA_API HttpTrace_Flush	HttpTrace_getFLushCallback (void)

BA_API void	HttpTrace_vprintf (int prio, const char *fmt, va_list argList)
	Write data to the trace buffer. More...

BA_API void	HttpTrace_printf (int prio, const char *fmt,...)
	Write data to the trace buffer. More...

BA_API void	HttpTrace_write (int prio, const char *buf, int len)
	Write data to the trace buffer. More...

BA_API void	HttpTrace_flush (void)
	Force a flush on data in trace buffer; i.e., call the flush callback. More...

BA_API void	HttpTrace_setRequest (BaBool cmd)
	Enable or disable request-line tracing. More...

BA_API void	HttpTrace_setRequestHeaders (BaBool cmd)
	If enabled, the web-server dumps the content of the request header to the trace buffer. More...

BA_API void	HttpTrace_setResponseHeaders (BaBool cmd)
	If enabled, the web-server dumps the content of the response header to the trace buffer. More...

BA_API void	HttpTrace_setResponseBody (BaBool cmd)
	If enabled, the web-server dumps the content of the response body to the trace buffer. More...

BA_API void	HttpTrace_setHttp11State (BaBool cmd)
	If enabled, prints the status for each active client connection of the internal "HTTP 1.1 persistent connection" state machine to the trace buffer. More...

BA_API void	HttpTrace_setReqBufOverflow (BaBool cmd)
	Report when an HTTP request exceeds the configured request buffer. More...

BA_API int	HttpTrace_setBufSize (int size)
	Set trace buffer size. More...

BA_API void	HttpTrace_close (void)
	Release the trace buffer and disable output without flushing pending bytes. More...

BA_API BufPrint *	HttpTrace_getWriter (void)
	Get and lock the trace BufPrint object. More...

BA_API void	HttpTrace_releaseWriter (void)
	Release a writer lock obtained by a successful getWriter call. More...

Macro Definition Documentation

◆ HttpTrace_isHttp11StateSet

#define HttpTrace_isHttp11StateSet ( ) (HttpTrace_getTraceCmds() & HttpTrace_doHttp11StateMask ? TRUE : FALSE)

Returns: TRUE when this trace category is enabled, otherwise FALSE.

◆ HttpTrace_isRequestHeadersSet

#define HttpTrace_isRequestHeadersSet ( ) (HttpTrace_getTraceCmds() & HttpTrace_doRequestHeadersMask ? TRUE : FALSE)

Returns: TRUE when this trace category is enabled, otherwise FALSE.

◆ HttpTrace_isRequestSet

#define HttpTrace_isRequestSet ( ) (HttpTrace_getTraceCmds() & HttpTrace_doRequestMask ? TRUE : FALSE)

Returns: TRUE when this trace category is enabled, otherwise FALSE.

◆ HttpTrace_isResponseBodySet

#define HttpTrace_isResponseBodySet ( ) (HttpTrace_getTraceCmds() & HttpTrace_doResponseBodyMask ? TRUE : FALSE)

Returns: TRUE when this trace category is enabled, otherwise FALSE.

◆ HttpTrace_isResponseHeadersSet

#define HttpTrace_isResponseHeadersSet ( ) (HttpTrace_getTraceCmds() & HttpTrace_doResponseHeadersMask ? TRUE : FALSE)

Returns: TRUE when this trace category is enabled, otherwise FALSE.

Typedef Documentation

◆ HttpTrace

typedef struct HttpTrace HttpTrace

Buffered diagnostic output and optional HTTP protocol tracing.

Install a flush callback at startup to enable output. If the library is built without HTTP_TRACE, output functions have no effect. This header enables HTTP_TRACE by default unless NO_HTTP_TRACE is defined.

Priority zero is highest. A message is emitted when its priority is less than or equal to the configured filter (initially 5). Optional HTTP trace categories are initially disabled and use priority 5 when enabled.

Output is flushed when the buffer fills, after a write that leaves a newline in the buffer, or by an explicit flush(). Partial lines may remain buffered. The default payload buffer is approximately 80 bytes.

Configure the callback and buffer size at startup, before concurrent use. Do not change or close the trace while a writer is locked. Output functions serialize access with the trace mutex; the callback executes under that mutex and must not call back into trace output.

See also: HttpTrace::setFLushCallback

◆ HttpTrace_Flush

typedef void(* HttpTrace_Flush) (char *buf, int bufLen)

Consume buffered trace output synchronously.

Parameters

[in,out]	buf	Borrowed trace buffer, valid only during the callback. The callback may write a NUL at buf[bufLen], but must not retain or free buf.
[in]	bufLen	Number of payload bytes; the buffer has room for one more byte. Data need not be NUL-terminated on entry. The callback runs while the trace mutex is held; do not call trace output or writer-lock APIs from it.

Function Documentation

◆ HttpTrace_close()

BA_API void HttpTrace_close ( void )

Release the trace buffer and disable output without flushing pending bytes.

Call at shutdown after all trace users and writer locks have stopped. No output or error status is returned.

◆ HttpTrace_flush()

BA_API void HttpTrace_flush ( void )

Force a flush on data in trace buffer; i.e., call the flush callback.

◆ HttpTrace_getFLushCallback()

BA_API HttpTrace_Flush HttpTrace_getFLushCallback ( void )

Returns: Currently installed callback, or NULL when tracing is disabled. Inspect during startup; this function does not acquire the trace mutex.

◆ HttpTrace_getWriter()

BA_API BufPrint * HttpTrace_getWriter ( void )

Get and lock the trace BufPrint object.

Returns: Borrowed locked writer, or NULL when tracing is disabled. Call releaseWriter exactly once only after a non-NULL result. Writing through this object bypasses the priority filter. Do not free it.

See also: releaseWriter; HttpTraceWriteLock

◆ HttpTrace_printf()

BA_API void HttpTrace_printf	(	int	prio,
		const char *	fmt,
			...
	)

Write data to the trace buffer.

Works just like the regular printf function.

Parameters

prio	See HttpTrace::setPrio.
fmt	See BufPrint::printf

◆ HttpTrace_releaseWriter()

BA_API void HttpTrace_releaseWriter ( void )

Release a writer lock obtained by a successful getWriter call.

Flushes pending output containing a newline before unlocking.

See also: HttpTraceWriteLock

◆ HttpTrace_setBufSize()

BA_API int HttpTrace_setBufSize ( int size )

Set trace buffer size.

The default buffer is 80 characters long. This function is not re-entrant, and you should therefore call this function at system startup.

Parameters

size	Positive buffer allocation size in bytes; use at least 81. The payload capacity can be one byte smaller. Existing buffered data is discarded when replacing the buffer. Call only during startup.

Returns: 0 on success, -1 on allocation failure (which disables tracing). Without HTTP_TRACE, the stub returns 0 without allocating storage.

◆ HttpTrace_setFLushCallback()

BA_API void HttpTrace_setFLushCallback ( HttpTrace_Flush fcb )

The HTTP_TRACE compile time macro adds the trace library to the Barracuda library, but the trace functions will have no effect if you do not provide a callback function.

This function is not re-entrant; therefore, you should call this function at system startup.

The following example dumps data to the console:

void flush2Console(char* buf, int bufLen)
{
   // The trace buffer is always > bufLen
   buf[bufLen] = 0; // convert to string
   printf("%s",buf);
}
.
.
HttpTrace_setFLushCallback(flush2Console);

Newline-terminated output is flushed automatically. To deliver partial lines promptly, flush explicitly, for example after a dispatcher poll.

for(;;)
{
   myDispatcher->run(1000);
   HttpTrace::flush();
}

Parameters

[in] fcb Callback retained until replaced, or NULL to disable output. Allocation failure during initialization leaves tracing disabled; HttpTrace_getFLushCallback returns NULL in that case.

◆ HttpTrace_setHttp11State()

BA_API void HttpTrace_setHttp11State ( BaBool cmd )

If enabled, prints the status for each active client connection of the internal "HTTP 1.1 persistent connection" state machine to the trace buffer.

The state machine can be in one of 5 states. As an example, a non-persistent connection will go through the following states for each request:

Connection 56c1f0 3944 trans: Free -> Connected
Connection 56c1f0 3944 trans: Connected -> Running
Connection 56c1f0 3944 trans: Running -> Terminated
Connection 56c1f0 -001 trans: Terminated -> Free

A persistent HTTP connection is in one of the Connected or Running states.

Connection 56c290 3944 trans: Connected -> Running
Connection 56c290 3944 trans: Running -> Connected
Connection 56c290 3944 trans: Connected -> Running
Connection 56c290 3944 trans: Running -> Connected
Connection 56c290 3944 trans: Connected -> Running
Connection 56c290 3944 trans: Running -> Connected

Parameters

[in] cmd TRUE enables this trace category; FALSE disables it.

◆ HttpTrace_setPrio()

BA_API int HttpTrace_setPrio ( int prio )

Set the trace message priority filter.

Priority 0 is the highest priority. Setting the priority to say 10 means that only trace messages with a priority less than or equal to 10 will be printed to the trace buffer.

Parameters

prio	Maximum message priority to emit; use 0-255 [default=5]

Returns: previous priority.

◆ HttpTrace_setReqBufOverflow()

BA_API void HttpTrace_setReqBufOverflow ( BaBool cmd )

Report when an HTTP request exceeds the configured request buffer.

Parameters

[in] cmd TRUE enables reporting; FALSE disables it.

See also: HttpServerConfig::setRequest

◆ HttpTrace_setRequest()

BA_API void HttpTrace_setRequest ( BaBool cmd )

Enable or disable request-line tracing.

If enabled, the web-server prints the first line in the request header to the trace buffer.

Example:

68.5.99.169 GET "intro.html" Mozilla/5.0 (Macintosh; U; PPC Mac OS X Mach-O; en-US; rv:1.7) Gecko/20040623 Camino/0.8

Parameters

cmd	TRUE to enable request-line tracing.

◆ HttpTrace_setRequestHeaders()

BA_API void HttpTrace_setRequestHeaders ( BaBool cmd )

If enabled, the web-server dumps the content of the request header to the trace buffer.

Parameters

cmd	TRUE to enable request-header tracing.

◆ HttpTrace_setResponseBody()

BA_API void HttpTrace_setResponseBody ( BaBool cmd )

If enabled, the web-server dumps the content of the response body to the trace buffer.

Warning: this generates an enormous amount of trace data.

Parameters

cmd	TRUE to enable response-body tracing.

◆ HttpTrace_setResponseHeaders()

BA_API void HttpTrace_setResponseHeaders ( BaBool cmd )

If enabled, the web-server dumps the content of the response header to the trace buffer.

Parameters

cmd	TRUE to enable response-header tracing.

◆ HttpTrace_vprintf()

BA_API void HttpTrace_vprintf	(	int	prio,
		const char *	fmt,
		va_list	argList
	)

Write data to the trace buffer.

Works just like the regular vprintf function.

Parameters

prio	See HttpTrace::setPrio.
fmt	See BufPrint::vprintf
argList	See BufPrint::vprintf more information.

◆ HttpTrace_write()

BA_API void HttpTrace_write	(	int	prio,
		const char *	buf,
		int	len
	)

Write data to the trace buffer.

Parameters

prio	See HttpTrace::setPrio.
buf	Required input buffer, borrowed for the duration of the call.
len	Byte count; any negative value uses strlen(buf), requiring a NUL-terminated string. Zero writes no bytes.

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ HttpTrace_isHttp11StateSet

◆ HttpTrace_isRequestHeadersSet

◆ HttpTrace_isRequestSet

◆ HttpTrace_isResponseBodySet

◆ HttpTrace_isResponseHeadersSet

Typedef Documentation

◆ HttpTrace

◆ HttpTrace_Flush

Function Documentation

◆ HttpTrace_close()

◆ HttpTrace_flush()

◆ HttpTrace_getFLushCallback()

◆ HttpTrace_getWriter()

◆ HttpTrace_printf()

◆ HttpTrace_releaseWriter()

◆ HttpTrace_setBufSize()

◆ HttpTrace_setFLushCallback()

◆ HttpTrace_setHttp11State()

◆ HttpTrace_setPrio()

◆ HttpTrace_setReqBufOverflow()

◆ HttpTrace_setRequest()

◆ HttpTrace_setRequestHeaders()

◆ HttpTrace_setResponseBody()

◆ HttpTrace_setResponseHeaders()

◆ HttpTrace_vprintf()

◆ HttpTrace_write()