4.4. EventRegister()


	Chapter 4. Plug-and-Play and Power Management Functions

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`() [4.5], or `NULL` if the event registration fails.
hWD	Handle to WinDriver's kernel-mode driver as received from `WD_Open`() [5.2]
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 unconfigured and detached 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`() [6.1] (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`() [4.4] 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].

Remarks

This function wraps the low-level WD_EventRegister(), WD_EventPull(), WD_EventSend() and InterruptEnable() [2.18] 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;
}


4.3. PcmciaEventCreate()		4.5. EventUnregister()