4.3. 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
NameTypeInput/Output
phEventHANDLE*Output
hWDHANDLEInput
pEventWD_EVENT*Input
• hEventDWORDOutput
• dwEventTypeWD_EVENT_TYPEInput
• dwActionDWORDInput
• dwEventIdDWORDN/A
• hKernelPlugInDWORDInput
• dwOptionsDWORDN/A
dwOptionsDWORDInput
• uunion 
 * Pcistruct 
  • cardIdWD_PCI_ID 
   * dwVendorIdDWORDInput
   * dwDeviceIdDWORDInput
  • pciSlotWD_PCI_SLOT
   * dwBusDWORDInput
   * dwSlotDWORDInput
   * dwFunctionDWORDInput
 * UsbstructInput
 * IpcstructN/A
• dwNumMatchTablesDWORDInput
• matchTablesWDU_MATCH_TABLE[1]Input
pFunc typedef void (*EVENT_HANDLER)(
  WD_EVENT *pEvent,
  void *pData);
Input
pDatavoidInput
Description
NameDescription
phEvent Pointer to the handle to be used in calls to EventUnregister() [4.4], or NULL if the event registration fails.
hWDHandle to WinDriver's kernel-mode driver as received from WD_Open() [5.2]
pEvent The criteria set for registering to receive event notifications.
• hEvent Optional handle to be used by the low-level WD_EventUnregister() function; Zero when event registration fails.
• dwEventType Event type. Can be either WD_EVENT_TYPE_PCI — for a PCI card, WD_EVENT_TYPE_USB — for a USB device or WD_EVENT_TYPE_IPC for an IPC related event (see WD_EVENT_TYPE enumeration values)
• 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 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
• 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.3] is called, WD_EventSend() will be called automatically after the callback function exits.
• uDevice information union:
 * PciPCI card information:
  • cardIdCard 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.
  • pciSlotPCI slot information:
   * dwBus PCI bus number to register to. If zero, register to all PCI buses.
   * dwSlotPCI slot to register to. If zero, register to all slots.
   * dwFunction PCI function to register to. If zero, register to all functions.
 * UsbUSB device information — relevant only for USB devices
 * IpcIPC message information - used internally by WinDriver
• dwNumMatchTablesRelevant only for USB devices
• matchTablesRelevant 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.17] functions.

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