|  | Home | Documentation | Debugging and logging updated by Robert van Engelen |

Debugging and logging

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

## Macros

#define | DEBUG
| User-definable macro to enable debugging and logging.
#define | SOAP_DEBUG
| User-definable macro, enables #DEBUG mode for runtime debug logs, but without enabling #SOAP_MEM_DEBUG memory debugging.
#define | DEBUG_STAMP
| User-definable macro to enable debugging and logging with time stamps.
#define | SOAP_MEM_DEBUG
| User-definable macro to enable memory debugging without #SOAP_DEBUG logging.

## Functions

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

## Detailed Description

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

This module describes 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

## ◆ DEBUG

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

## ◆ DEBUG_STAMP

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

## ◆ SOAP_DEBUG

#define SOAP_DEBUG

User-definable macro, enables #DEBUG mode for runtime debug logs, but without enabling #SOAP_MEM_DEBUG memory debugging.

This macro can 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.

## ◆ SOAP_MEM_DEBUG

#define SOAP_MEM_DEBUG

User-definable macro to enable memory debugging without #SOAP_DEBUG 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

## ◆ logging()

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.

## ◆ soap_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);
soap_reset_logging_stats
void soap_reset_logging_stats(struct soap *soap)
Reset messaging statistics with the logging plugin.
soap_logging_stats
void soap_logging_stats(struct soap *soap, size_t *sent, size_t *recv)
Collect messaging statistics with the logging plugin.
logging
int logging(struct soap *, struct soap_plugin *, void *)
The logging plugin registration function.
soap_register_plugin
int soap_register_plugin(struct soap *soap, int(*fcreate)(struct soap *, struct soap_plugin *, void *))
Register a plugin.
soap
Context with the engine state.
Definition stdsoap2.h:2929
soap::sent
*Internal buffer with partial data received or partial data to be sent
Definition stdsoap2.h:4319

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

## ◆ soap_reset_logging_stats()

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

## ◆ soap_set_logging_inbound()

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);
soap::fopen
*Callback that opens a socket connection to a server endpoint SOAP_SOCKET(* fopen)(struct soap *soap, const char *endpoint, const char *host, int port)
Definition stdsoap2.h:4635
soap::fclose
*Callback that closes the current socket connection int(* fclose)(struct soap *soap)
Definition stdsoap2.h:4660
soap_set_logging_inbound
void soap_set_logging_inbound(struct soap *soap, FILE *fd)
Specify inbound message logging with the logging plugin.

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

## ◆ soap_set_logging_outbound()

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);
soap_set_logging_outbound
void soap_set_logging_outbound(struct soap *soap, FILE *fd)
Specify outbound message logging with the logging plugin.

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

## ◆ soap_set_recv_logfile()

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");
soap_set_recv_logfile
void soap_set_recv_logfile(struct soap *soap, const char *logfile)
Specify a file name to save messages received.
soap_set_test_logfile
void soap_set_test_logfile(struct soap *soap, const char *logfile)
Specify a file name to save debugging info.
soap_set_sent_logfile
void soap_set_sent_logfile(struct soap *soap, const char *logfile)
Specify a file name to save messages sent.

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

## ◆ soap_set_sent_logfile()

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

## ◆ soap_set_test_logfile()

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