6.4.3 Tracing the Exchange of Data Packets

QSMM provides facilities for tracing events related to interaction sides. You can specify the types of events dumped to a trace log using a bitmask defined as a subset of the following macros merged by bitwise “or.”

Macro: QSMM_SIDE_TRACE_API

Side API calls entry and exit. API functions with a side handle argument dump a function name, the names and values of function arguments, and a returned value.

Macro: QSMM_SIDE_TRACE_MSG

The contents of data packets sent from an interaction side to other interaction sides dumped as byte arrays in hexadecimal notation.

Use the following functions to query or set a bitmask of types of events dumped to a trace log.

Function: unsigned int qsmm_get_side_trace_flags (qsmm_side_t side)

This function returns the bitmask of types of events dumped to the trace log of an interaction side. The interaction side is the originator of those events. This function returns a bitmask set by the function qsmm_set_side_trace_flags or a default bitmask (see a remark below) if the latter function not yet called.

Function: void qsmm_set_side_trace_flags (qsmm_side_t side, unsigned int flags)

This function sets to flags the bitmask of types of events dumped to the trace log of an interaction side. The interaction side is the originator of those events. The function does not check whether the bitmask is correct.

The function qsmm_side_create initializes the bitmask of types of events dumped to a trace log to QSMM_SIDE_TRACE_MSG.

An interaction side does not dump events to a trace log unless the side has an assigned stream for the trace log. Use the following functions to get or set the stream.

Function: FILE * qsmm_get_side_trace_stream (qsmm_side_t side)

This function returns a stream for the trace log of an interaction side. If the side does not have the stream assigned, the function returns NULL.

Function: void qsmm_set_side_trace_stream (qsmm_side_t side, FILE *filep)

This function sets to filep the stream for the trace log of an interaction side. The NULL stream disables dumping log messages.

Use the following functions to dump a custom formatted message, for example, containing additional information about a data packet sent or received.

Function: void qsmm_side_trace_f (qsmm_side_t side, const char *fmt, ...)

Function: void qsmm_side_trace_fv (qsmm_side_t side, const char *fmt, va_list ap)

These functions write a formatted message to the trace log of an interaction side. They append the character ‘\n’ to the message and flush the stream buffer. If the trace log not set, the functions have no effect. The meaning of fmt argument and subsequent arguments of qsmm_side_trace_f function is the same as in the function printf. The meaning of fmt and ap arguments of qsmm_side_trace_fv function is the same as in the function vprintf.