ASN1C C/C++ Common Runtime  ASN1C v7.2.x
Classes | Macros | Typedefs | Enumerations | Functions | Variables
Diagnostic trace functions

Classes

struct  OSRTPrintStream
 

Macros

#define RTDIAG1(pctxt, msg)
 
#define RTDIAG2(pctxt, msg, a)
 
#define RTDIAG3(pctxt, msg, a, b)
 
#define RTDIAG4(pctxt, msg, a, b, c)
 
#define RTDIAG5(pctxt, msg, a, b, c, d)
 
#define RTDIAGU(pctxt, ucstr)
 
#define RTHEXDUMP(pctxt, buffer, numocts)
 
#define RTDIAGCHARS(pctxt, buf, nchars)
 
#define RTDIAGSTRM2(pctxt, msg)
 
#define RTDIAGSTRM3(pctxt, msg, a)
 
#define RTDIAGSTRM4(pctxt, msg, a, b)
 
#define RTDIAGSTRM5(pctxt, msg, a, b, c)
 
#define RTHEXDUMPSTRM(pctxt, buffer, numocts)
 
#define RTDIAGSCHARS(pctxt, buf, nchars)
 

Typedefs

typedef void(* rtxPrintCallback) (void *pPrntStrmInfo, const char *fmtspec, va_list arglist)
 
typedef struct OSRTPrintStream OSRTPrintStream
 

Enumerations

enum  OSRTDiagTraceLevel { OSRTDiagError, OSRTDiagWarning, OSRTDiagInfo, OSRTDiagDebug }
 

Functions

int rtxSetPrintStream (OSCTXT *pctxt, rtxPrintCallback myCallback, void *pStrmInfo)
 
int rtxSetGlobalPrintStream (rtxPrintCallback myCallback, void *pStrmInfo)
 
int rtxPrintToStream (OSCTXT *pctxt, const char *fmtspec,...)
 
int rtxDiagToStream (OSCTXT *pctxt, const char *fmtspec, va_list arglist)
 
int rtxPrintStreamRelease (OSCTXT *pctxt)
 
void rtxPrintStreamToStdoutCB (void *pPrntStrmInfo, const char *fmtspec, va_list arglist)
 
void rtxPrintStreamToFileCB (void *pPrntStrmInfo, const char *fmtspec, va_list arglist)
 
OSBOOL rtxDiagEnabled (OSCTXT *pctxt)
 
OSBOOL rtxSetDiag (OSCTXT *pctxt, OSBOOL value)
 
OSBOOL rtxSetGlobalDiag (OSBOOL value)
 
void rtxDiagPrint (OSCTXT *pctxt, const char *fmtspec,...)
 
void rtxDiagStream (OSCTXT *pctxt, const char *fmtspec,...)
 
void rtxDiagHexDump (OSCTXT *pctxt, const OSOCTET *data, size_t numocts)
 
void rtxDiagStreamHexDump (OSCTXT *pctxt, const OSOCTET *data, size_t numocts)
 
void rtxDiagPrintChars (OSCTXT *pctxt, const char *data, size_t nchars)
 
void rtxDiagStreamPrintChars (OSCTXT *pctxt, const char *data, size_t nchars)
 
void rtxDiagStreamPrintBits (OSCTXT *pctxt, const char *descr, const OSOCTET *data, size_t bitIndex, size_t nbits)
 
void rtxDiagSetTraceLevel (OSCTXT *pctxt, OSRTDiagTraceLevel level)
 
OSBOOL rtxDiagTraceLevelEnabled (OSCTXT *pctxt, OSRTDiagTraceLevel level)
 

Variables

OSRTPrintStream g_PrintStream
 

Detailed Description

These functions add diagnostic tracing to the generated code to assist in finding where a problem might occur. Calls to these macros and functions are added when the -trace command-line argument is used. The diagnostic message can be turned on and off at both C compile and run-time. To C compile the diagnostics in, the _TRACE macro must be defined (-D_TRACE). To turn the diagnostics on at run-time, the rtxSetDiag function must be invoked with the value argument set to TRUE.

Typedef Documentation

◆ OSRTPrintStream

Structure to hold information about a global PrintStream.

◆ rtxPrintCallback

typedef void(* rtxPrintCallback) (void *pPrntStrmInfo, const char *fmtspec, va_list arglist)

Callback function definition for print stream.

Function Documentation

◆ rtxDiagEnabled()

OSBOOL rtxDiagEnabled ( OSCTXT pctxt)

This function is used to determine if diagnostic tracing is currently enabled for the specified context. It returns true if enabled, false otherwise.

Parameters
pctxtPointer to context structure.
Returns
Boolean result.

◆ rtxDiagHexDump()

void rtxDiagHexDump ( OSCTXT pctxt,
const OSOCTET *  data,
size_t  numocts 
)

This function is used to print a diagnostics hex dump of a section of memory.

Parameters
pctxtPointer to context structure.
dataStart address of memory to dump.
numoctsNumber of bytes to dump.

◆ rtxDiagPrint()

void rtxDiagPrint ( OSCTXT pctxt,
const char *  fmtspec,
  ... 
)

This function is used to print a diagnostics message to stdout. Its parameter specification is similar to that of the C runtime printf method. The fmtspec argument may contain % style modifiers into which variable arguments are substituted. This function is called in the generated code via the RTDIAG macros to allow diagnostic trace call to easily be compiled out of the object code.

Parameters
pctxtPointer to context structure.
fmtspecA printf-like format specification string describing the message to be printed (for example, "string %s, ivalue %d\n"). A special character sequence (~L) may be used at the beginning of the string to select a trace level (L would be replaced with E for Error, W for warning, I for info, or D for debug).
...Variable list of parameters to be substituted into the format string.

◆ rtxDiagPrintChars()

void rtxDiagPrintChars ( OSCTXT pctxt,
const char *  data,
size_t  nchars 
)

This function is used to print a given number of characters to standard output. The buffer containing the characters does not need to be null-terminated.

Parameters
pctxtPointer to context structure.
dataStart address of character string.
ncharsNumber of characters to dump (this assumes 1-byte chars).

◆ rtxDiagSetTraceLevel()

void rtxDiagSetTraceLevel ( OSCTXT pctxt,
OSRTDiagTraceLevel  level 
)

This function is used to set the maximum trace level for diagnostic trace messages. Values are ERROR, WARNING, INFO, or DEBUG. The special string start sequence (~L) described in rtxDiagPrint function documentation is used to set a message level to be compared with the trace level.

Parameters
pctxtPointer to context structure.
levelTrace level to be set.

◆ rtxDiagStream()

void rtxDiagStream ( OSCTXT pctxt,
const char *  fmtspec,
  ... 
)

This function conditionally outputs diagnostic trace messages to an output stream defined within the context. A code generator embeds calls to this function into the generated source code when the -trace option is specified on the command line (note: it may embed the macro version of these calls - RTDIAGSTREAMx - so that these calls can be compiled out of the final code.

See also
rtxDiagPrint

◆ rtxDiagStreamHexDump()

void rtxDiagStreamHexDump ( OSCTXT pctxt,
const OSOCTET *  data,
size_t  numocts 
)

This function is used to print a diagnostics hex dump of a section of memory to a print stream.

Parameters
pctxtPointer to context structure.
dataStart address of memory to dump.
numoctsNumber of bytes to dump.

◆ rtxDiagStreamPrintBits()

void rtxDiagStreamPrintBits ( OSCTXT pctxt,
const char *  descr,
const OSOCTET *  data,
size_t  bitIndex,
size_t  nbits 
)

This function is used to print a given number of bits as '1' or '0' values to a print stream.

Parameters
pctxtPointer to context structure.
descrDescriptive text to print before bits
dataStart address of binary data.
bitIndexZero-based offset to first bit to be printed
nbitsNumber of bits to dump

◆ rtxDiagStreamPrintChars()

void rtxDiagStreamPrintChars ( OSCTXT pctxt,
const char *  data,
size_t  nchars 
)

This function is used to print a given number of characters to a print stream. The buffer containing the characters does not need to be null-terminated.

Parameters
pctxtPointer to context structure.
dataStart address of character string.
ncharsNumber of characters to dump (this assumes 1-byte chars).

◆ rtxDiagToStream()

int rtxDiagToStream ( OSCTXT pctxt,
const char *  fmtspec,
va_list  arglist 
)

Diagnostics print-to-stream function. This is the same as the rtxPrintToStream function except that it checks if diagnostic tracing is enabled before invoking the callback function.

Parameters
pctxtPointer to context to be used.
fmtspecA printf-like format specification string describing the message to be printed (for example, "string %s, ivalue %d\n").
arglistA variable list of arguments passed as va_list
Returns
Completion status, 0 on success, negative value on failure

◆ rtxDiagTraceLevelEnabled()

OSBOOL rtxDiagTraceLevelEnabled ( OSCTXT pctxt,
OSRTDiagTraceLevel  level 
)

This function tests if a given trace level is enabled.

Parameters
pctxtPointer to context structure.
levelTrace level to check.
Returns
True if enabled.

◆ rtxPrintStreamRelease()

int rtxPrintStreamRelease ( OSCTXT pctxt)

This function releases the memory held by PrintStream in the context

Parameters
pctxtPointer to a context for which the memory has to be released.
Returns
Completion status, 0 on success, negative value on failure

◆ rtxPrintStreamToFileCB()

void rtxPrintStreamToFileCB ( void *  pPrntStrmInfo,
const char *  fmtspec,
va_list  arglist 
)

Standard callback function for use with print-to-stream for writing to a file.

Parameters
pPrntStrmInfoUser-defined information for use by the callback function. This is supplied by the user at the time the callback is registered. This parameter should be set to the file pointer (FILE*) to which data is to be written.
fmtspecFormat specification of the data to be printed. This is supplied by the print-to-stream utility.
arglistVariable argument list. This is supplied by the print-to-stream utility.

◆ rtxPrintStreamToStdoutCB()

void rtxPrintStreamToStdoutCB ( void *  pPrntStrmInfo,
const char *  fmtspec,
va_list  arglist 
)

Standard callback function for use with print-to-stream for writing to stdout.

Parameters
pPrntStrmInfoUser-defined information for use by the callback function. This is supplied by the user at the time the callback is registered. In this case, no user-defined information is required, so the argument can be set to NULL when the callback is registered.
fmtspecFormat specification of the data to be printed. This is supplied by the print-to-stream utility.
arglistVariable argument list. This is supplied by the print-to-stream utility.

◆ rtxPrintToStream()

int rtxPrintToStream ( OSCTXT pctxt,
const char *  fmtspec,
  ... 
)

Print-to-stream function which in turn calls the user registered callback function of the context for printing. If no callback function is registered it prints to standard output by default.

Parameters
pctxtPointer to context to be used.
fmtspecA printf-like format specification string describing the message to be printed (for example, "string %s, ivalue %d\n").
...A variable list of arguments.
Returns
Completion status, 0 on success, negative value on failure

◆ rtxSetDiag()

OSBOOL rtxSetDiag ( OSCTXT pctxt,
OSBOOL  value 
)

This function is used to turn diagnostic tracing on or off at run-time on a per-context basis. Code generated using ASN1C or XBinder or a similar code generator must use the -trace command line option to enable diagnostic messages. The generated code must then be C compiled with _TRACE defined for the code to be present.

Parameters
pctxtPointer to context structure.
valueBoolean switch: TRUE turns tracing on, FALSE off.
Returns
Prior setting of the diagnostic trace switch in the context.

Referenced by OSRTContext::setDiag().

◆ rtxSetGlobalDiag()

OSBOOL rtxSetGlobalDiag ( OSBOOL  value)

This function is used to turn diagnostic tracing on or off at run-time on a global basis. It is similar to rtxSetDiag except tracing is enabled within all contexts.

Parameters
valueBoolean switch: TRUE turns tracing on, FALSE off.
Returns
Prior setting of the diagnostic trace switch in the context.

◆ rtxSetGlobalPrintStream()

int rtxSetGlobalPrintStream ( rtxPrintCallback  myCallback,
void *  pStrmInfo 
)

This function is for setting the callback function for a PrintStream. This version of the function sets a callback at the global level.

Parameters
myCallbackPointer to a callback print function.
pStrmInfoPointer to user defined PrintInfo structure where users can store information required by the callback function across calls. Ex. An open File handle for callbak function which directs stream to a file.
Returns
Completion status, 0 on success, negative value on failure

◆ rtxSetPrintStream()

int rtxSetPrintStream ( OSCTXT pctxt,
rtxPrintCallback  myCallback,
void *  pStrmInfo 
)

This function is for setting the callback function for a PrintStream. Once a callback function is set, then all print and debug output ia sent to the defined callback function.

Parameters
pctxtPointer to a context in which callback print function will be set
myCallbackPointer to a callback print function.
pStrmInfoPointer to user defined PrintInfo structure where users can store information required by the callback function across calls. Ex. An open File handle for callbak function which directs stream to a file.
Returns
Completion status, 0 on success, negative value on failure

Variable Documentation

◆ g_PrintStream

OSRTPrintStream g_PrintStream

Global PrintStream