Barracuda Application Server C/C++ Reference
HttpTrace Struct Reference

Trace the communication between a client and the server. More...

#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 BufPrintgetWriter ()
 Get and lock the trace BufPrint object. More...
 
static void releaseWriter (void)
 Release the trace. More...
 
static void setRequest (bool cmd)
 If enabled, the web-server prints the first line in the request header to the trace buffer. More...
 
static void setRequestHeaders (bool cmd)
 If enabled, the web-server dumps the content of the request header to the trace buffer.
 
static void setResponseHeaders (bool cmd)
 If enabled, the web-server dumps the content of the response header to the trace buffer.
 
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. More...
 
static void flush ()
 Force a flush on data in trace buffer; i.e., call the flush callback.
 

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.
//By default, print all web-server access to the trace buffer.
}

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.

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
prioSee HttpTrace::setPrio.
fmtSee 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.

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

◆ 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(const 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.

struct timeval timeout;
timeout.tv_sec = 1;
timeout.tv_usec = 0;
for(;;)
{
myDispatcher->run(&timeout);
}

◆ 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
prioThe 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

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

◆ 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.

◆ 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
prioSee HttpTrace::setPrio.
fmtSee BufPrint::vprintf
argListSee BufPrint::vprintf more information.

◆ write()

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

Write data to the trace buffer.

Parameters
prioSee HttpTrace::setPrio.
bufa pointer to the buffer/string.
lenis optional, not needed for strings.
HttpTrace::printf
static void printf(int prio, const char *fmt,...)
Write data to the trace buffer.
Definition: HttpTrace.h:370
HttpTrace::setFLushCallback
static void setFLushCallback(HttpTrace_Flush fcb)
The HTTP_TRACE compile time macro adds the trace library to the Barracuda library,...
Definition: HttpTrace.h:366
HttpTrace::setBufSize
static int setBufSize(int size)
Set trace buffer.
Definition: HttpTrace.h:395
HttpTrace::flush
static void flush()
Force a flush on data in trace buffer; i.e., call the flush callback.
Definition: HttpTrace.h:397
HttpTrace::setRequest
static void setRequest(bool cmd)
If enabled, the web-server prints the first line in the request header to the trace buffer.
Definition: HttpTrace.h:383