6.9 WFMSetTraceLevel

HRESULT WFMSetTraceLevel( hService, dwTraceLevel )

Sets the specified trace level(s) at run time; to be used for debugging and testing purposes.

Parameters HSERVICE hService

Handle to the service provider as returned by WFSOpen or WFSAsyncOpen.

DWORD dwTraceLevel

The level(s) of tracing being requested. See below.

Mode Immediate

Comments Issuing WFMSetTraceLevel for a service enables tracing on that service at various levels. Five standard trace levels are predefined:

 WFS_TRACE_API 0x00000001

Trace all input and output parameters of all API function calls using the specified hService.

 WFS_TRACE_ALL_API 0x00000002

Trace all input and output parameters of all API function calls associated with the service provider identified by the specified hService, not just the ones associated with the specified hService.

 WFS_TRACE_SPI 0x00000004

Trace all input and output parameters of all SPI function calls associated with the specified hService, as well as all notification and event messages generated by the service provider for the hService.

 WFS_TRACE_ALL_SPI 0x00000008

As for WFS_TRACE_ALL_API, but trace all SPI, notification and event activity on the service provider, not just that associated with the specified hService.

 WFS_TRACE_MGR 0x00000010

Trace the support functions (WFMxxxxx) of the XFS Manager.

Other standard trace levels may be defined in the future, and a range of trace level values (the high order 16 bits of this parameter) is reserved for use by individual service providers. Examples of other functions that may be traced include network messages, interactions between the service provider and service, and device interface interaction.

Trace level values can be ORed together in a single dwTraceLevel parameter to request more than one kind of tracing be started. A NULL value stops all tracing.

If more than one process may be using the trace facility, this function should always be preceded with a call to the WFMGetTraceLevel function. This value returned by this function is ORed together with the new trace level(s), and the resulting value is used with WFMSetTraceLevel, thus adding the new trace level(s) to whatever the existing trace level(s) had been,

This function has the highest priority to the XFS Manager and the service provider; they activate the trace as soon as possible. Note that the XFS Manager performs all the traces defined above, other than the completion and event messages posted by the service providers.

WFSOpen and WFSAsyncOpen also include an option to set these trace levels, to allow the open process itself to be traced.

Error Codes If the function return is not WFS_SUCCESS, it is one of the following error conditions:

WFS_ERR_INVALID_HSERVICE

The hService parameter is not a valid service handle.

WFS_ERR_INVALID_TRACELEVEL

The dwTraceLevel parameter does not correspond to a valid trace level or set of levels.

WFS_ERR_NOT_STARTED

The application has not previously performed a successful WFSStartUp.

WFS_ERR_OP_IN_PROGRESS

A blocking operation is in progress on the thread; only WFSCancelBlockingCall and WFSIsBlocking are permitted at this time.

See Also WFMGetTraceLevel, WFPSetTraceLevel, WFSOpen, WFSAsyncOpen