4.4 EventRegister

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 un-configured 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