HttpTrace Struct Reference

Detailed Description

Trace the communication between a client and the server.

This class is enabled if the Barracuda Web-Server library is compiled with macro HTTP_TRACE enabled. The methods in this class have no effect if the trace functionality is not enabled by macro HTTP_TRACE. You must also provide a console callback function before the trace functionality is activated. See HttpTrace::setFLushCallback for more information.

Most user functions in the web-server return 0 on success and an error number if any of the parameters were incorrect. The web-server also prints the error to the trace buffer, and it is for this reason recommended that you always provide a trace callback function when doing development.

The trace library is typically used by your code when debugging. The printf and write member functions take the message priority as argument. You can, therefore, design the code such that more important functions use a higher priority. See HttpTrace::setPrio for more information.

The web-server is using the trace library to write information about user requests and response data. This is by default disabled. If enabled, the web-server writes the data to the trace buffer by using priority 5. See the setXXX functions for more information.

The trace callback function can write to internal memory, your screen (if you have one) or use an SMTP library.

Here is a trace callback function example that is using the SMTP library:

//The flushTrace function is called by HttpTrace when trace buffer is full.
static void flushTrace(char* buf, int bufLen)
{
   const char* from = "device1@realtimelogic.com";
   const char* to = "bill@mycompany.com";
   const char* subject = "DEVICE 1 TRACE DATA";
   const char* smtpServer = "192.168.0.1";
   SMTP smtp(from, to, subject, smtpServer);
   smtp.write(buf, bufLen);
}
 
//This function should be called at startup
void myInit(void)
{
   // The default HttpTrace buffer is 80 bytes,
   // which would lead to a lot of emails.
   HttpTrace::setBufSize(2000);
   HttpTrace::setFLushCallback(flushTrace);
   //By default, print all web-server access to the trace buffer.
   HttpTrace::setRequest(true);
}

The methods in the HttpTrace class are re-entrant, except for HttpTrace::setFLushCallback and HttpTrace::setBufSize. These two functions, if used, must be called at system startup.

#include <HttpTrace.h>

Static Public Member Functions
static void	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...
static void	vprintf (int prio, const char *fmt, va_list argList)
	Write data to the trace buffer. More...
static void	printf (int prio, const char *fmt,...)
	Write data to the trace buffer. More...
static void	write (int prio, const char *buf, int len=-1)
	Write data to the trace buffer. More...
static int	setPrio (int prio)
	Set the trace message priority filter. More...
static BufPrint *	getWriter ()
	Get and lock the trace BufPrint object. More...
static void	releaseWriter (void)
	Release the trace. More...
static void	setRequest (bool cmd)
	Enable or disable request-line tracing. More...
static void	setRequestHeaders (bool cmd)
	If enabled, the web-server dumps the content of the request header to the trace buffer. More...
static void	setResponseHeaders (bool cmd)
	If enabled, the web-server dumps the content of the response header to the trace buffer. More...
static void	setResponseBody (bool cmd)
	If enabled, the web-server dumps the content of the response body to the trace buffer. More...
static void	setHttp11State (bool 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...
static void	setReqBufOverflow (bool cmd)
	Prints "ReqBufOverflow" if enabled and the HttpRequest buffer overflows. More...
static int	setBufSize (int size)
	Set trace buffer size. More...
static void	flush ()
	Force a flush on data in trace buffer; i.e., call the flush callback.
static bool	isRequestSet ()
	Returns true if request-line tracing is enabled.
static bool	isRequestHeadersSet ()
	Returns true if request-header tracing is enabled.
static bool	isResponseHeadersSet ()
	Returns true if response-header tracing is enabled.
static bool	isResponseBodySet ()
	Returns true if response-body tracing is enabled.
static bool	isHttp11StateSet ()
	Returns true if HTTP/1.1 connection-state tracing is enabled.

Member Function Documentation

getWriter()

BufPrint * HttpTrace::getWriter ( )

static

Get and lock the trace BufPrint object.

See also

releaseWriter

HttpTraceWriteLock

printf()

void HttpTrace::printf ( int  prio, const char *  fmt,   ...  )

static

Write data to the trace buffer.

Works just like the regular printf function.

Parameters

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

releaseWriter()

void HttpTrace::releaseWriter ( void  )

static

Release the trace.

Use in combination with getWriter.

See also

HttpTraceWriteLock

setBufSize()

int HttpTrace::setBufSize ( int  size )

static

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	New trace buffer size in bytes.

Returns

0 on success or a negative error code.

setFLushCallback()

void HttpTrace::setFLushCallback ( HttpTrace_Flush  fcb )

static

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);

Please note that data written to the trace is not automatically flushed. It may be a good idea to run the web-server in poll mode and flush the data manually after the web-server is run.

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

setHttp11State()

void HttpTrace::setHttp11State ( bool  cmd )

static

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

setPrio()

int HttpTrace::setPrio ( int  prio )

static

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 greater than or equal to 10 will be printed to the trace buffer.

Parameters

prio	The priority [default=5]

Returns

previous priority.

setReqBufOverflow()

void HttpTrace::setReqBufOverflow ( bool  cmd )

static

Prints "ReqBufOverflow" if enabled and the HttpRequest buffer overflows.

A buffer overflow occurs if the client request stream overflows the request buffer. This could potentially be an indication of a Buffer Overflow Attack. Buffer Overflow Attacks are very common against web servers. Barracuda is immune to Buffer Overflow Attacks. See HttpServerConfig::setRequest for more information.

setRequest()

void HttpTrace::setRequest ( bool  cmd )

static

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.

setRequestHeaders()

void HttpTrace::setRequestHeaders ( bool  cmd )

static

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

Parameters

cmd	TRUE to enable request-header tracing.

setResponseBody()

void HttpTrace::setResponseBody ( bool  cmd )

static

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.

setResponseHeaders()

void HttpTrace::setResponseHeaders ( bool  cmd )

static

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

Parameters

cmd	TRUE to enable response-header tracing.

vprintf()

void HttpTrace::vprintf ( int  prio, const char *  fmt, va_list  argList  )

static

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.

write()

void HttpTrace::write ( int  prio, const char *  buf, int  len = -1  )

static

Write data to the trace buffer.

Parameters

prio	See HttpTrace::setPrio.
buf	a pointer to the buffer/string.
len	is optional, not needed for strings.