PBSetComponent and PBSetContext

Components and Contexts Overview, Working With Components and Contexts

VOID PBSetComponent (PB_COMPONENT* pcp, PCTSTR pszName, PCTSTR pszMessageKey, BOOL blEnable, ULONG ulExclude)

VOID WPBSetComponent (PB_COMPONENT* pcp, ULONG ulNameStringId, HINSTANCE hModule, PCTSTR pszMessageKey, BOOL blEnable, ULONG ulExclude)

VOID PBSetContext (PB_CONTEXT* pcx, PCTSTR pszName, BOOL blEnable, ULONG ulExclude)

VOID WPBSetContext (PB_CONTEXT* pcx, ULONG ulNameStringId, HINSTANCE hModule, BOOL blEnable, ULONG ulExclude)

Parameters

pcp Pointer to PB_COMPONENT structure to modify.

pcx Pointer to PB_CONTEXT structure to modify.

ulNameStringId String table resource identifier of string that will be used for the szName member of the component or context.

hModule Handle to module containing the string table into which ulNameStringId is an index.

The remaining parameters simply map one for one to the elements of the PB_COMPONENT and PB_CONTEXT structures.

Remarks

Each of these functions provides a thread-safe method for initializing or changing component or context structures, allowing modification of the structures on one thread while another thread may be using them to log. When these structures are not shared by multiple threads, they can be manipulated directly without the use of these functions.

Versions of these functions are provided that accept either ANSI or Unicode strings. WPBSetComponent and WPBSetContext provide further support for internationalization. These functions allow the component and context names to be stored in a string table resource, although it is usually not necessary to internationalize strings used solely for internal code diagnostic purposes. It would be appropriate to use these functions only when the output of Paul Bunyan is to be viewed by persons other than developers. Note that internationalized message keys just add unnecessary complexity and are invisible anyway. 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.

Passing NULL for pszName or pszMessageKey causes that string to be unchanged by the function call. This allows modification of blEnable, ulExclude without affecting the strings. Note that the first time a component or context is initialized, pszName and pszMessageKey cannot be NULL since this is an instruction to ignore those strings and they would consequently be uninitialized. To set an element to an empty string, use "" or L"" instead of NULL. Also, to change the message key or other elements without changing the name, call PBSetComponent or PBSetContext with pszName = NULL instead of WPBSetComponent or WPBSetContext with ulNameStringId == 0 since 0 is a perfectly valid string id and as such cannot be treated as equivalent to NULL.

In the event of failure or if Paul Bunyan is not installed then these functions will set the strings to .