C and C++ API Overview, What’s a Log Message, Samples
C functions
C++ overloads
VOID PBLog (PB_LOC_ARGS, ULONG ulMsgType, PCTSTR pszFormat = NULL, ...)
Parameters
Note that in the above prototypes the location macro PB_LOC_ARGS expands to PC[W]STR pszFile, ULONG ulLine.
pcp Pointer to PB_COMPONENT structure. Overrides thread and module defaults if non-NULL.
pcx Pointer to PB_CONTEXT structure. Overrides thread and module defaults if non-NULL.
pszFile Source code file name. Usually obtained via the __FILE__ preprocessor macro.
ulLine Source code line number. Usually obtained via the __LINE__ preprocessor macro.
ulMsgType One of the message type constants.
pszFormat Format string that is ultimately passed to the run-time library function vsprintf.
hModule Handle to module containing string table resource into which ulFormatStringId is an index.
ulFormatStringId String table resource identifier of the format string that is ultimately passed to the run-time library function vsprintf.
valArgs Stack pointer for ANSI version of va_start macro.
Remarks
Versions of these functions are provided that accept either ANSI or Unicode strings. ANSI strings are always converted to Unicode when log messages are generated. The macros PBLog, VPBLog, and WPBLog expand to the ANSI or Unicode versions of the functions depending on preprocessor definitions and both versions (e.g. PBLogA and PBLogW) are always simultaneously available in the lib to support explicit logging with mixed character sets.
WPBLog provides further support for internationalization. The log message format string can be specified as a resource table entry. In this case it is recommended that insertion elements into the format string only be used for data that does not need to be internationalized, e.g. file names or numerical data. It is usually not necessary to internationalize strings used solely for internal code diagnostic purposes. It would be appropriate to use this function only when the output of Paul Bunyan is to be viewed by persons other than developers. Passing NULL for the hModule parameter results in an attempt to load the string from the calling process. If the string table resides in a DLL, the parameter must be non-NULL.
VPBLog is useful when writing helper functions that construct messages for other code.
All functions are called using the location / type macros as follows:
PBLog (PB_VERBOSE, “Hello %s.”, “world”);