Debugging and logging

This module defines compile-time flags and functions for run-time debugging and logging. More...

Macros
#define	DEBUG
	User-definable macro to enable debugging and logging. More...
#define	SOAP_DEBUG
	User-definable macro, identical behavior as DEBUG but more portable. More...
#define	DEBUG_STAMP
	User-definable macro to enable debugging and logging with time stamps. More...
#define	SOAP_MEM_DEBUG
	User-definable macro to enable memory debugging without logging. More...

Functions
void	soap_set_recv_logfile (struct soap *soap, const char *logfile)
	Specify a file name to save messages received. More...
void	soap_set_sent_logfile (struct soap *soap, const char *logfile)
	Specify a file name to save messages sent. More...
void	soap_set_test_logfile (struct soap *soap, const char *logfile)
	Specify a file name to save debugging info. More...
void	soap_set_logging_inbound (struct soap *soap, FILE *fd)
	Specify inbound message logging with the logging plugin. More...
void	soap_set_logging_outbound (struct soap *soap, FILE *fd)
	Specify outbound message logging with the logging plugin. More...
void	soap_logging_stats (struct soap *soap, size_t *sent, size_t *recv)
	Collect messaging statistics with the logging plugin. More...
void	soap_reset_logging_stats (struct soap *soap)
	Reset messaging statistics with the logging plugin. More...
int	logging (struct soap *, struct soap_plugin *, void *)
	The logging plugin registration function. More...

Detailed Description

This module defines compile-time flags and functions for run-time debugging and logging.

This module defines the following compile-time flags and functions to specify log files:

• DEBUG
• SOAP_DEBUG
• DEBUG_STAMP
• SOAP_MEM_DEBUG
• soap_set_recv_logfile
• soap_set_sent_logfile
• soap_set_test_logfile

Alternatively, the logging plugin can be used without setting DEBUG to efficiently log messages and collect statistics:

• soap_set_logging_inbound
• soap_set_logging_outbound
• soap_logging_stats
• soap_reset_logging_stats

Macro Definition Documentation

#define DEBUG

User-definable macro to enable debugging and logging.

When this macro is defined at compile time (undefined by default), the engine runs in debug mode to produce RECV.log, SENT.log, and TEST.log files for debugging purposes:

• RECV.log contains messages received, concatenated
• SENT.log contains messages sent, concatenated
• TEST.log contains debugging information to identify issues Debugging with DEBUG incurs significant run-time overhead and should only be used for debugging purposes.

Example:

c++ -D DEBUG -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
./client
ls *.log
RECV.log SENT.log TEST.log

See also

SOAP_DEBUG, DEBUG_STAMP, SOAP_MEM_DEBUG, soap_set_recv_logfile, soap_set_sent_logfile, soap_set_test_logfile and the message logging plugin gsoap/plugin/logging.c as a faster alternative.

Note

The libgsoap, libgsoap++, libgsoapssl and libgsoapssl++ libraries should not be used when a project is (re)compiled with DEBUG, because these libraries are built by default without debugging enabled. Use ./configure --enable-debug to rebuild the libraries with -D DEBUG.

#define DEBUG_STAMP

User-definable macro to enable debugging and logging with time stamps.

When this macro is defined at compile time (undefined by default), the engine runs in debug mode to produce RECV.log, SENT.log, and TEST.log files with time stamps for debugging purposes:

• RECV.log contains messages received, concatenated
• SENT.log contains messages sent, concatenated
• TEST.log contains debugging information with time stamps to identify issues This incurs significant run-time overhead and should only be used for debugging purposes.

Example:

c++ -D DEBUG_STAMP -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
./client
ls *.log
RECV.log SENT.log TEST.log

See also

DEBUG, SOAP_DEBUG, SOAP_MEM_DEBUG, soap_set_recv_logfile, soap_set_sent_logfile, soap_set_test_logfile and the message logging plugin gsoap/plugin/logging.c as a faster alternative.

Note

The libgsoap, libgsoap++, libgsoapssl and libgsoapssl++ libraries should not be used when a project is (re)compiled with DEBUG_STAMP, because these libraries are built by default without debugging enabled.

#define SOAP_DEBUG

User-definable macro, identical behavior as DEBUG but more portable.

This macro should be used when the DEBUG macro is reserved by the IDE for other purposes.

See also

DEBUG, DEBUG_STAMP, SOAP_MEM_DEBUG, soap_set_recv_logfile, soap_set_sent_logfile, soap_set_test_logfile.

#define SOAP_MEM_DEBUG

User-definable macro to enable memory debugging without logging.

When this macro is defined at compile time (undefined by default), the engine runs in debug mode to detect memory corruption errors but does not produce RECV.log, SENT.log and TEST.log files and avoids the significant run-time overhead of logging. Use this macro when memory debugging is required without logging overhead.

Example:

c++ -D SOAP_MEM_DEBUG -o client stdsoap2.cpp soapC.cpp soapClient.cpp client.cpp
./client
ls *.log
ls: No match.

See also

DEBUG, SOAP_DEBUG, DEBUG_STAMP.

Note

The libgsoap, libgsoap++, libgsoapssl and libgsoapssl++ libraries should not be used when a project is (re)compiled with SOAP_MEM_DEBUG, because these libraries are built by default without debugging enabled.

Function Documentation

int logging	(	struct soap *	,
		struct soap_plugin *	,
		void *
	)

The logging plugin registration function.

The logging plugin API is declared and defined in gsoap/plugin/logging.h and gsoap/plugin/logging.c.

See also

soap_set_logging_inbound, soap_set_logging_outbound, soap_logging_stats, soap_reset_logging_stats.

void soap_logging_stats	(	struct soap *	soap,
		size_t *	sent,
		size_t *	recv
	)

Collect messaging statistics with the logging plugin.

This function collects the recorded messaging statistics, namely the number of bytes received from inbound messages and the number of bytes sent to outbound messages.

Example:

#include "soapH.h"
#include "plugin/logging.h"

struct soap *soap = soap_new();
soap_register_plugin(soap, logging);
... // send and receive messages
size_t sent, recv;
soap_logging_stats(soap, &sent, &recv);
printf("Bytes sent = %zu bytes received = %zu\n", sent, recv);
soap_reset_logging_stats(soap);

Note

This function is declared and defined in gsoap/plugin/logging.h and gsoap/plugin/logging.c and requires the logging plugin and does not require DEBUG.

See also

soap_set_logging_inbound, soap_set_logging_outbound, soap_reset_logging_stats.

Parameters

soap	soap context
sent	pointer to variable to assign
recv	pointer to variable to assign

void soap_reset_logging_stats

(

struct soap *

soap

)

Reset messaging statistics with the logging plugin.

This function resets the recorded messaging statistics.

Note

This function is declared and defined in gsoap/plugin/logging.h and gsoap/plugin/logging.c and requires the logging plugin and does not require DEBUG.

See also

soap_set_logging_inbound, soap_set_logging_outbound, soap_logging_stats.

Parameters

soap	soap context

void soap_set_logging_inbound	(	struct soap *	soap,
		FILE *	fd
	)

Specify inbound message logging with the logging plugin.

This function enables inbound message logging. Inbound messages are recorded to the specified file descriptor. Logging is disabled by passing a NULL file descriptor parameter.

Example:

#include "soapH.h"
#include "plugin/logging.h"

struct soap *soap = soap_new();
FILE *fd = fopen("logs/recv.log", "w");
soap_register_plugin(soap, logging);
soap_set_logging_inbound(soap, fd);
... // send and receive messages
soap_set_logging_inbound(soap, NULL);
fclose(fd);

Note

This function is declared and defined in gsoap/plugin/logging.h and gsoap/plugin/logging.c and requires the logging plugin and does not require DEBUG.

See also

soap_set_logging_outbound, soap_logging_stats, soap_reset_logging_stats.

Parameters

soap	soap context
fd	file descriptor to record inbound messages

void soap_set_logging_outbound	(	struct soap *	soap,
		FILE *	fd
	)

Specify outbound message logging with the logging plugin.

This function enables outbound message logging. Outbound messages are recorded to the specified file descriptor. Logging is disabled by passing a NULL file descriptor parameter.

Example:

#include "soapH.h"
#include "plugin/logging.h"

struct soap *soap = soap_new();
FILE *fd = fopen("logs/sent.log", "w");
soap_register_plugin(soap, logging);
soap_set_logging_outbound(soap, fd);
... // send and receive messages
soap_set_logging_outbound(soap, NULL);
fclose(fd);

Note

This function is declared and defined in gsoap/plugin/logging.h and gsoap/plugin/logging.c and requires the logging plugin and does not require DEBUG.

See also

soap_set_logging_inbound, soap_logging_stats, soap_reset_logging_stats.

Parameters

soap	soap context
fd	file descriptor to record outbound messages

void soap_set_recv_logfile	(	struct soap *	soap,
		const char *	logfile
	)

Specify a file name to save messages received.

This function sets the specified file path name logfile to save all messages received. Messages are appended to the specified file. Disables logging when logfile is NULL. This function requires compilation with DEBUG.

Example:

#include "soapH.h"

struct soap *soap = soap_new();
soap_set_recv_logfile(soap, "logs/thread_1_recv.log");
soap_set_sent_logfile(soap, "logs/thread_1_sent.log");
soap_set_test_logfile(soap, "logs/thread_1_test.log");

Note

Requires compilation with DEBUG.

See also

soap_set_sent_logfile and the message logging plugin gsoap/plugin/logging.c as a faster alternative.

Parameters

soap	soap context
logfile	path name of the log file or NULL to disable logging

void soap_set_sent_logfile	(	struct soap *	soap,
		const char *	logfile
	)

Specify a file name to save messages sent.

This function sets the specified file path name logfile to save the messages sent. Messages are appended to the specified file. Disables logging when logfile is NULL. This function requires compilation with DEBUG.

Example:

#include "soapH.h"

struct soap *soap = soap_new();
soap_set_recv_logfile(soap, "logs/thread_1_recv.log");
soap_set_sent_logfile(soap, "logs/thread_1_sent.log");
soap_set_test_logfile(soap, "logs/thread_1_test.log");

Note

Requires compilation with DEBUG.

See also

soap_set_recv_logfile and the message logging plugin gsoap/plugin/logging.c as a faster alternative.

Parameters

soap	soap context
logfile	path name of the log file or NULL to disable logging

void soap_set_test_logfile	(	struct soap *	soap,
		const char *	logfile
	)

Specify a file name to save debugging info.

This function sets the specified file path name logfile to save debugging info generated by the engine and by the generated code. Disables logging when logfile is NULL. This function requires compilation with DEBUG.

Example:

#include "soapH.h"

struct soap *soap = soap_new();
soap_set_recv_logfile(soap, "logs/thread_1_recv.log");
soap_set_sent_logfile(soap, "logs/thread_1_sent.log");
soap_set_test_logfile(soap, "logs/thread_1_test.log");

Note

Requires compilation with DEBUG.

Parameters

soap	soap context
logfile	path name of the log file or NULL to disable logging