4.4 EventRegister()

PURPOSE

$\bullet$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
$\bullet$phEvent	HANDLE*	Output
$\bullet$hWD	HANDLE	Input
$\bullet$pEvent	WD_EVENT*	Input
$\gg$handle	DWORD	Output
$\gg$dwAction	DWORD	Input
$\gg$dwStatus	DWORD	N/A
$\gg$dwEventId	DWORD	N/A
$\gg$dwCardType	WD_BUS_TYPE	Input
$\gg$hKernelPlugIn	DWORD	Input
$\gg$dwOptions	DWORD	Input
$\gg$u	union
$\diamond$Pci	struct
$\triangleright$cardId	WD_PCI_ID
$\rightarrow$dwVendorId	DWORD	Input
$\rightarrow$dwDeviceId	DWORD	Input
$\triangleright$pciSlot	WD_PCI_SLOT
$\rightarrow$dwBus	DWORD	Input
$\rightarrow$dwSlot	DWORD	Input
$\rightarrow$dwFunction	DWORD	Input
$\diamond$Usb	struct	Input
$\diamond$Pcmcia	struct
$\triangleright$deviceId	WD_PCMCIA_ID
$\rightarrow$wManufacturerId	WORD	Input
$\rightarrow$wCardId	WORD	Input
$\triangleright$slot	WD_PCMCIA_SLOT
$\rightarrow$uBus	BYTE	Input
$\rightarrow$uSocket	BYTE	Input
$\rightarrow$uFunction	BYTE	Input
$\rightarrow$uPadding	BYTE	N/A
$\gg$dwEventVer	DWORD	N/A
$\gg$dwNumMatchTables	DWORD	Input
$\gg$matchTables	WDU_MATCH_TABLE[1]	Input
$\bullet$pFunc	typedef void (*EVENT_HANDLER)(     WD_EVENT *pEvent,     void *pData);	Input
$\bullet$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.
$\bullet$ handle	Optional handle to be used by the low-level WD_EventUnregister() function; Zero when event registration fails.
$\bullet$ dwAction	A bit-mask indicating which events to register to: Plug-and-Play events: $\bullet$WD_INSERT - Device was attached and configured by the operating system's Plug-and-Play manager $\bullet$WD_REMOVE - Device was un-configured and detached by the operating system's Plug-and-Play manager Device power state: $\bullet$WD_POWER_CHANGED_D0 - Full power $\bullet$WD_POWER_CHANGED_D1 - Low sleep $\bullet$WD_POWER_CHANGED_D2 - Medium sleep $\bullet$WD_POWER_CHANGED_D3 - Full sleep $\bullet$WD_POWER_SYSTEM_WORKING - Fully on Systems power state: $\bullet$WD_POWER_SYSTEM_SLEEPING1 - Fully on but sleeping $\bullet$WD_POWER_SYSTEM_SLEEPING2 - CPU off, memory on, PCI/PCMCIA on $\bullet$WD_POWER_SYSTEM_SLEEPING3 - CPU off, memory is in refresh, PCI/PCMCIA on aux power $\bullet$WD_POWER_SYSTEM_HIBERNATE - OS saves context before shutdown $\bullet$WD_POWER_SYSTEM_SHUTDOWN - No context saved
$\bullet$ 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)
$\bullet$ hKernelPlugIn	Handle to Kernel PlugIn returned from WD_KernelPlugInOpen() [6.1] (when using the Kernel PlugIn to handle the events)
$\bullet$dwOptions	Can be either zero or: $\bullet$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.
$\bullet$ u	Device information union:
$\gg$ Pci	PCI card information:
$\diamond$ cardId	Card information structure:
$\triangleright$ dwVendorId	PCI vendor ID to register to. If zero, register to all PCI vendor IDs.
$\triangleright$ dwDeviceId	PCI card ID to register to. If zero, register to all PCI device IDs.
$\diamond$ pciSlot	PCI slot information:
$\triangleright$ dwBus	PCI bus number to register to. If zero, register to all PCI buses.
$\triangleright$ dwSlot	PCI slot to register to. If zero, register to all slots.
$\triangleright$ dwFunction	PCI function to register to. If zero, register to all functions.
$\gg$ Usb	USB device information - relevant only for USB devices
$\gg$ Pcmcia	PCMCIA card information:
$\diamond$ deviceId	PCMCIA card ID information structure:
$\triangleright$ wManufacturerId	PCMCIA Manufacturer ID to register to. If zero, register to all PCMCIA manufacturer IDs.
$\triangleright$ wCardId	PCMCIA card ID to register to. If zero, register to all PCMCIA card IDs.
$\diamond$ slot	PCMCIA slot information structure:
$\triangleright$ uBus	PCMCIA bus number to register to. If zero, register to all PCMCIA buses.
$\triangleright$ uSocket	PCMCIA socket to register to. If zero, register to all sockets.
$\triangleright$ uFunction	PCMCIA function to register to. If zero, register to all functions.
$\bullet$ dwNumMatchTables	Relevant only for USB devices
$\bullet$ 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;
}