Print to Stream

The -genPrtToStrm option causes functions to be generated that print the contents of variables of generated types to an output stream via a user-defined callback function. The advantage of these functions is that a user can register a callback function, and then the print stream is automatically directed to the callback function. This makes it easier to support print-to-file or print-to-window type of functionalities. It also make it possible to create an optimized print-to-string capability by maintaining a structure that keeps track of the current end-of-string position in the output buffer. The generated print-to-string functions always must use the strlen run-time function to find the end position, an operation that becomes compute intensive in large string buffers that are constantly appended to.

It is possible to specify the name of a .c or .cpp file as an argument to this option to specify the name of the file to which these functions will be written. This is an optional argument. If not specified, the functions are written to separate files for each module in the source file. The format of the name of each file is <module>PrtToStrm.c. If an output filename is specified after the –genPrtToStrm qualifier, all functions are written to that file.

Before calling generated print-to-stream functions, a callback function should be registered. Otherwise, a default callback function will be used that directs the print stream to the standard output device.

The callback function is declared as:

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

The first parameter is user-defined data which will be passed to each invocation of the callback function. This parameter can be used to pass print stream specific data, for example, a file pointer if the callback function is to output data to a file. The second and third parameters to the callback function constitute the data to be printed, in the form of format specification followed by list of arguments. A simple callback function for printing to file can be defined as follows:

   void writeToFile (void* pPrntStrmInfo, const char* fmtspec, va_list arglist)
   {
      FILE * fp = (FILE*) pPrntStrmInfo;
      vfprintf (fp, fmtspec, arglist);
   }

Once the callback function is defined, it has to be registered with the runtime library. There are two types of registrations possible: 1. global, which applies to all print streams and, 2. context level, which applies to print streams associated with a particular context.

For registering a global callback use:

   rtxSetGlobalPrintStream (rtxPrintCallback myCallback, void* pStrmInfo);

For registering a context level callback use:

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

Once the callback function is registered, the calling of each generated print-to-stream function will result in output being directed to the callback function.

The print to stream functions are declared as follows:

   asn1PrtToStrm_<name> (OSCTXT *pctxt, const char* name, <name>* pvalue);

The name and pvalue arguments are the same as they were in the -print case.

The pctxt argument is used to specify an ASN1C context. If a valid context argument is passed and there is a context level callback registered, then that callback will be used. If there is no context level callback registered, or the pctxt argument is NULL, then the global callback will be used. If there is no global callback registered, the default callback will be used which writes the print output to stdout.

If C++ code generation is specified, setPrintStream and toStream methods are added to the ASN1C control class for the type. The setPrintStream method takes only myCallback and pStrmInfo arguments; the pctxt argument is obtained from the context pointer reference contained within the class. The toStream method takes only a name argument; the pctxt argument is derived from the context pointer reference within the class and the pvalue argument is obtained from the msgData reference contained within the class.