Export (0) Print
Expand All

Using DIFxAPI Event Logging

DIFxAPI supports logging events that occur during the preinstall, install, or uninstall of a driver package.

To register for event logging, an application calls the SetDifxLogCallback function to set a callback function, and supplies the following application-specific information:

  • Callback function that DIFxAPI calls every time that DIFxAPI reports an event.

  • Callback context that DIFxAPI passes back to the callback function with the event information.

To unregister for event logging, an application calls SetDifxLogCallback, and supplies NULL pointers for the callback function and the callback context.

Be aware that DIFxAPI version 2.1 also supports the DIFXAPISetLogCallback function, which was included starting with DIFxAPI version 2.0. DIFxAPI performs the same event logging operation whether you set a callback with SetDifxLogCallback or DIFXAPISetLogCallback. The only difference in the logging operation is the calling convention that is used to call the callback function, as follows:

  • Call SetDifxLogCallback to register a callback function that DIFxAPI calls by using the calling convention for Win32 API functions. Include the WINAPI macro in the function declaration of the callback function to specify the calling convention that is used for Win32 API functions.

  • Call DIFXAPISetCallback to register a callback function that DIFxAPI calls by using the default calling convention for the C programming language. Include the keyword modifier __cdecl in the function declaration of the callback function to specify the default calling convention for C.

DIFxAPI reports the following types of events and, for each event, a description of the event:

  • A success event that indicates that an operation succeeded

  • An information event that describes the context or progress of an operation

  • A warning event that describes a possible problem that is not a fatal error

  • An error event that indicates that an operation failed

DIFxAPI also reports the Microsoft Win32 error code, if any, that is associated with each event. Most information and warning events do not include a Win32 error code.

The following table provides examples of events and their event descriptions that DIFxAPI might typically log for a fictitious driver named "foo".

Event typeWin32 error value returnedDescription

Success

ERROR_SUCCESS

c:\driver\foo.inf is installed.

Information

(None)

No matching devices found in INF 'c:\foo\foo.inf'.

Warning

(None)

File 'foo.sys' referenced in driver package not found.

Error

ERROR_INVALID_NAME

Failed to copy 'foo.inf' to the DIFx driver store. (DIFxAPI returns this description if the file name is too long.)

 

The following code example shows how to register a callback function and callback context that DIFxAPI uses to log events.


#define UNICODE
#include "difxapi.h"
. . .
// Define a callback function
VOID WINAPI
 SomeLogCallback(
    DIFXAPI_LOG Event, 
    DWORD Error, 
 const TCHAR * pEventDescription, 
    PVOID CallbackContext
    ) {
  . . .
  // Callback function code
  . . .
}
. . .
// Declare a callback context
PVOID CallbackContext;
// Set the CallbackContext
. . .
// Call SetDifxLogCallback to register event logging
SetDifxLogCallback( SomeLogCallback, CallbackContext );

The following code example shows how to unregister for event logging by calling SetDifxLogCallback and supplying NULL pointers for the callback function and the callback context.


#define UNICODE
#include "difxapi.h"
. . .
// Unregister for event logging
SetDifxLogCallback( NULL, (PVOID)NULL );

For more information about preinstalling, installing, and uninstalling driver packages, see Preinstalling a PnP Function Driver Package, Installing Driver Packages, and Installing Driver Packages.

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft