A.2 WinDriver Functions Used by Go-HotSwap

A.2 WinDriver Functions Used by Go-HotSwap
	Appendix A. Function Reference

A.2.1 WD_Open()

Purpose

• Opens a handle to access the WinDriver kernel module. The handle is used by all WinDriver APIs, and therefore must be called before any other WinDriver API is called.

Prototype

HANDLE WD_Open(void);

Return Value

The handle to the WinDriver kernel module.
If device could not be opened, returns INVALID_HANDLE_VALUE.

Remarks

If you are a registered user, please refer to the documentation of WDC_DriverOpen() in the WinDriver PCI Manual, or to the documentation of the low-level WD_License() function in the WinDriver PCI Low-Level API Reference, for an example of how to register your WinDriver license.

Example

HANDLE hWD;

hWD = WD_Open();
if (hWD == INVALID_HANDLE_VALUE)
{
    printf("Cannot open WinDriver device\n");
}

A.2.2 WD_Version()

Purpose

• Returns the version number of the WinDriver kernel module currently running.

Prototype

DWORD WD_Version(
    HANDLE hWD,
    WD_VERSION *pVer);

Parameters

Name	Type	Input/Output
hWD	HANDLE	Input
pVer	WD_VERSION*
• dwVer	DWORD	Output
• cVer	CHAR[100]	Output

Description

Name	Description
hWD	Handle to WinDriver's kernel-mode driver as received from `WD_Open`() [A.2.1]
pVer	Pointer to a WinDriver version information structure:
dwVer	The version number
cVer	Version information string

Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [A.3].

Example

WD_VERSION ver;

BZERO(ver);
WD_Version(hWD, &ver);
printf("%s\n", ver.cVer);
if (ver.dwVer < WD_VER)
{
    printf("Error - incorrect WinDriver version\n");
}

A.2.3 WD_Close()

Purpose

• Closes the access to the WinDriver kernel module.

Prototype

void WD_Close(HANDLE hWD);

Parameters

Name	Type	Input/Output
hWD	HANDLE	Input

Description

Name	Description
hWD	Handle to WinDriver's kernel-mode driver as received from `WD_Open`() [A.2.1]

Return Value

None

Remarks

This function must be called when you finish using WinDriver kernel module.

Example

WD_Close(hWD);

A.2.4 PciEventCreate

Purpose

• Convenience function for allocating and initializing a PCI Plug-and-Play and power management event structure.

Prototype

WD_EVENT * DLLCALLCONV PciEventCreate(
    WD_PCI_ID cardId,
    WD_PCI_SLOT pciSlot,
    DWORD dwOptions,
    DWORD dwAction);

Parameters

Name	Type	Input/Output
cardId	WD_PCI_ID
• dwVendorId	DWORD	Input
• dwDeviceId	DWORD	Input
pciSlot	WD_PCI_SLOT
• dwBus	DWORD	Input
• dwSlot	DWORD	Input
• dwFunction	DWORD	Input
dwOptions	DWORD	Input
dwAction	DWORD	Input

Description

Name	Description
cardId	PCI card information structure:
• dwVendorId	PCI vendor ID to register to. If zero, register to all PCI vendor IDs.
• dwDeviceId	PCI card ID to register to. If zero, register to all PCI device IDs.
pciSlot	PCI slot information:
• dwBus	PCI bus number to register to. If zero, register to all PCI buses.
• dwSlot	PCI slot to register to. If zero, register to all slots.
• dwFunction	PCI function to register to. If zero, register to all functions.
dwOptions	Can be either zero or: • `WD_ACKNOWLEDGE` – If set, the user can perform actions on the requested event before acknowledging it. The OS waits on the event until the user calls `WD_EventSend`() If `EventRegister`() [A.2.6] is called, `WD_EventSend`() will be called automatically after the callback function exits.
dwAction	A bit-mask indicating which events to register to: Plug-and-Play events: • `WD_INSERT` – Device was attached and configured by the operating system's Plug-and-Play manager • `WD_REMOVE` – Device was un-configured and detached by the operating system's Plug-and-Play manager Hot Swap Plug-and-Play events: • `WD_CPCI_INSERT` – The Hot Swap Engine detected a physical card insertion, which has yet to be detected by the operating system's Plug-and-Play Manager. • `WD_CPCI_REMOVE` – The Hot Swap Engine detected a physical card removal, which has yet to be detected by the operating system's Plug-and-Play Manager. Device power state: • `WD_POWER_CHANGED_D0` – Full power • `WD_POWER_CHANGED_D1` – Low sleep • `WD_POWER_CHANGED_D2` – Medium sleep • `WD_POWER_CHANGED_D3` – Full sleep • `WD_POWER_SYSTEM_WORKING` – Fully on Systems power state: • `WD_POWER_SYSTEM_SLEEPING1` – Fully on but sleeping • `WD_POWER_SYSTEM_SLEEPING2` – CPU off, memory on, PCI on • `WD_POWER_SYSTEM_SLEEPING3` – CPU off, memory is in refresh, PCI on aux power • `WD_POWER_SYSTEM_HIBERNATE` – OS saves context before shutdown • `WD_POWER_SYSTEM_SHUTDOWN` – No context saved

Return Value

Returns a new structure for handling PCI Plug-and-Play and power management events, or NULL if the allocation failed.

Remarks

It is the responsibility of the caller to free the event structure returned by the function (using free()) when it is no longer needed.

Example

EventUnregister(event_handle);
PciEventCreate(cardId, pciSlot, WD_ACKNOWLEDGE, WD_INSERT | WD_REMOVE);

A.2.5 PcmciaEventCreate

Purpose

• Convenience function for allocating and initializing a PCMCIA Plug-and-Play and power management event structure.

Prototype

WD_EVENT * DLLCALLCONV PcmciaEventCreate(
  WD_PCMCIA_ID deviceId,
  WD_PCMCIA_SLOT pcmciaSlot,
  DWORD dwOptions,
  DWORD dwAction);

Parameters

Name	Type	Input/Output
deviceId	WD_PCMCIA_ID
• wManufacturerId	WORD	Input
• wCardId	WORD	Input
pcmciaSlot	WD_PCMCIA_SLOT
• uBus	BYTE	Input
• uSocket	BYTE	Input
• uFunction	BYTE	Input
• uPadding	BYTE	N/A
dwOptions	DWORD	Input
dwAction	DWORD	Input

Description

Name	Description
deviceId	PCMCIA card ID information structure:
• w ManufacturerId	PCMCIA Manufacturer ID to register to. If zero, register to all PCMCIA manufacturer IDs.
• wCardId	PCMCIA card ID to register to. If zero, register to all PCMCIA card IDs.
slot	PCMCIA slot information structure:
• uBus	PCMCIA bus number to register to. If zero, register to all PCMCIA buses.
• uSocket	PCMCIA socket to register to. If zero, register to all sockets.
• uFunction	PCMCIA function to register to. If zero, register to all functions.
dwOptions	Can be either zero or: • `WD_ACKNOWLEDGE` – If set, the user can perform actions on the requested event before acknowledging it. The OS waits on the event until the user calls `WD_EventSend`() If `EventRegister`() [A.2.6] is called, `WD_EventSend`() will be called automatically after the callback function exits.
dwAction	A bit-mask indicating which events to register to: Plug-and-Play events: • `WD_INSERT` – Device was attached and configured by the operating system's Plug-and-Play manager • `WD_REMOVE` – Device was un-configured and detached by the operating system's Plug-and-Play manager Hot Swap Plug-and-Play events: • `WD_CPCI_INSERT` – The Hot Swap Engine detected a physical card insertion, which has yet to be detected by the operating system's Plug-and-Play Manager. • `WD_CPCI_REMOVE` – The Hot Swap Engine detected a physical card removal, which has yet to be detected by the operating system's Plug-and-Play Manager. Device power state: • `WD_POWER_CHANGED_D0` – Full power • `WD_POWER_CHANGED_D1` – Low sleep • `WD_POWER_CHANGED_D2` – Medium sleep • `WD_POWER_CHANGED_D3` – Full sleep • `WD_POWER_SYSTEM_WORKING` – Fully on Systems power state: • `WD_POWER_SYSTEM_SLEEPING1` – Fully on but sleeping • `WD_POWER_SYSTEM_SLEEPING2` – CPU off, memory on, PCMCIA on • `WD_POWER_SYSTEM_SLEEPING3` – CPU off, memory is in refresh, PCMCIA on aux power • `WD_POWER_SYSTEM_HIBERNATE` – OS saves context before shutdown • `WD_POWER_SYSTEM_SHUTDOWN` – No context saved

Return Value

Returns a new events structure for handling PCMCIA Plug-and-Play and power management events, or NULL if the allocation failed.

Remarks

It is the responsibility of the caller to free the event structure returned by the function (using free()) when it is no longer needed.

Example

PciEventCreate(deviceId, pcmciaSlot, WD_ACKNOWLEDGE, WD_INSERT | WD_REMOVE);

A.2.6 EventRegister

Purpose

• Registers your application to receive Plug-and-Play and power management event notifications, according to a predefined set of criteria.
The function receives an event handler callback, which will be invoked upon the occurrence of a registered event.

Prototype

DWORD EventRegister(
    HANDLE *phEvent,
    HANDLE hWD,
    WD_EVENT *pEvent,
    EVENT_HANDLER pFunc,
    void *pData);

Parameters

Name	Type	Input/Output
phEvent	HANDLE*	Output
hWD	HANDLE	Input
pEvent	WD_EVENT*	Input
• handle	DWORD	Output
• dwAction	DWORD	Input
• dwStatus	DWORD	N/A
• dwEventId	DWORD	N/A
• dwCardType	WD_BUS_TYPE	Input
• hKernelPlugIn	DWORD	Input
dwOptions	DWORD	Input
• u	union
* Pci	struct
• cardId	WD_PCI_ID
* dwVendorId	DWORD	Input
* dwDeviceId	DWORD	Input
• pciSlot	WD_PCI_SLOT
* dwBus	DWORD	Input
* dwSlot	DWORD	Input
* dwFunction	DWORD	Input
* Usb	struct	Input
* Pcmcia	struct
• deviceId	WD_PCMCIA_ID
* wManufacturerId	WORD	Input
* wCardId	WORD	Input
• slot	WD_PCMCIA_SLOT
* uBus	BYTE	Input
* uSocket	BYTE	Input
* uFunction	BYTE	Input
* uPadding	BYTE	N/A
• dwEventVer	DWORD	N/A
• dwNumMatchTables	DWORD	Input
• matchTables	WDU_MATCH_TABLE[1]	Input
pFunc	typedef void (EVENT_HANDLER)( WD_EVENT pEvent, void *pData);	Input
pData	void	Input

Description

Name	Description
phEvent	Pointer to the handle to be used in calls to `EventUnregister`() [A.2.7], or `NULL` if the event registration fails.
hWD	Handle to WinDriver's kernel-mode driver as received from `WD_Open`() [A.2.1]
pEvent	The criteria set for registering to receive event notifications.
• handle	Optional handle to be used by the low-level `WD_EventUnregister`() function; Zero when event registration fails.
• dwAction	A bit-mask indicating which events to register to: Plug-and-Play events: • `WD_INSERT` – Device was attached and configured by the operating system's Plug-and-Play manager • `WD_REMOVE` – Device was un-configured and detached by the operating system's Plug-and-Play manager Hot Swap Plug-and-Play events: • `WD_CPCI_INSERT` – The Hot Swap Engine detected a physical card insertion, which has yet to be detected by the operating system's Plug-and-Play Manager. • `WD_CPCI_REMOVE` – The Hot Swap Engine detected a physical card removal, which has yet to be detected by the operating system's Plug-and-Play Manager. Device power state: • `WD_POWER_CHANGED_D0` – Full power • `WD_POWER_CHANGED_D1` – Low sleep • `WD_POWER_CHANGED_D2` – Medium sleep • `WD_POWER_CHANGED_D3` – Full sleep • `WD_POWER_SYSTEM_WORKING` – Fully on Systems power state: • `WD_POWER_SYSTEM_SLEEPING1` – Fully on but sleeping • `WD_POWER_SYSTEM_SLEEPING2` – CPU off, memory on, PCI/PCMCIA on • `WD_POWER_SYSTEM_SLEEPING3` – CPU off, memory is in refresh, PCI/PCMCIA on aux power • `WD_POWER_SYSTEM_HIBERNATE` – OS saves context before shutdown • `WD_POWER_SYSTEM_SHUTDOWN` – No context saved
• dwCardType	Card type. Can be either `WD_BUS_PCI` – for a PCI card, `WD_BUS_PCMCIA` – for a PCMCIA card, or `WD_BUS_USB` – for a USB device (see the `WD_BUS_TYPE` enumeration values)
• hKernelPlugIn	Handle to Kernel PlugIn returned from `WD_KernelPlugInOpen`() (when using the Kernel PlugIn to handle the events)
dwOptions	Can be either zero or: • `WD_ACKNOWLEDGE` – If set, the user can perform actions on the requested event before acknowledging it. The OS waits on the event until the user calls `WD_EventSend`() If `EventRegister`() [A.2.6] is called, `WD_EventSend`() will be called automatically after the callback function exits.
• u	Device information union:
* Pci	PCI card information:
• cardId	Card information structure:
* dwVendorId	PCI vendor ID to register to. If zero, register to all PCI vendor IDs.
* dwDeviceId	PCI card ID to register to. If zero, register to all PCI device IDs.
• pciSlot	PCI slot information:
* dwBus	PCI bus number to register to. If zero, register to all PCI buses.
* dwSlot	PCI slot to register to. If zero, register to all slots.
* dwFunction	PCI function to register to. If zero, register to all functions.
* Usb	USB device information – relevant only for USB devices
* Pcmcia	PCMCIA card information:
• deviceId	PCMCIA card ID information structure:
* wManufacturerId	PCMCIA Manufacturer ID to register to. If zero, register to all PCMCIA manufacturer IDs.
* wCardId	PCMCIA card ID to register to. If zero, register to all PCMCIA card IDs.
• slot	PCMCIA slot information structure:
* uBus	PCMCIA bus number to register to. If zero, register to all PCMCIA buses.
* uSocket	PCMCIA socket to register to. If zero, register to all sockets.
* uFunction	PCMCIA function to register to. If zero, register to all functions.
• dwNumMatchTables	Relevant only for USB devices
• matchTables	Relevant only for USB devices
pFunc	The callback function to call upon receipt of event notification.
pData	Pointer to the data to pass to the `pFunc` callback (`NULL` if there is no data to pass).

Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [A.3].

Remarks

This function wraps the low-level WD_EventRegister(), WD_EventPull(), WD_EventSend() and InterruptEnable() functions.

Example

HANDLE *event_handle;
WD_EVENT event;
DWORD dwStatus;
BZERO(event);
event.dwAction = WD_INSERT | WD_REMOVE;
event.dwCardType = WD_BUS_PCI;
dwStatus = EventRegister(&event_handle, hWD, &event,
    event_handler_func, NULL);
if (dwStatus!=WD_STATUS_SUCCESS)
{
    printf("Failed register\n");
    return;
}

A.2.7 EventUnregister

Purpose

• Unregisters from receiving Plug-and-Play and power management event notifications.

Prototype

DWORD EventUnregister(HANDLE hEvent);

Parameters

Name	Type	Input/Output
hEvent	HANDLE	Input

Description

Name	Description
hEvent	Handle received from `EventRegister`() [A.2.6]

Return Value

Returns WD_STATUS_SUCCESS (0) on success, or an appropriate error code otherwise [A.3].

Remarks

This function wraps WD_EventUnregister() and InterruptDisable().

Example

EventUnregister(event_handle);