IDirectInputDevice8::SetEventNotification

Specifies an event that is to be set when the device state changes. It is also used to turn off event notification.

HRESULT SetEventNotification(
  HANDLE hEvent  
);

Parameters

hEvent

Handle to the event that is to be set when the device state changes. Microsoft® DirectInput® uses the Microsoft® Win32® SetEvent function on the handle when the state of the device changes. If the hEvent parameter is NULL, notification is disabled.

The application can create the handle as either a manual-reset or autoreset event by using the Microsoft® Win32® CreateEvent function. If the event is created as an autoreset event, the operating system automatically resets the event once a wait has been satisfied. If the event is created as a manual-reset event, it is the application's responsibility to call the Win32 ResetEvent function to reset it. DirectInput does not call the Win32 ResetEvent function for event notification handles. Most applications create the event as an automatic-reset event.

Return Values

If the method succeeds, the return value is DI_OK or DI_POLLEDDEVICE.

If the method fails, the return value can be one of the following error values:

Remarks

A device state change is defined as any of the following:

• A change in the position of an axis
• A change in the state (pressed or released) of a button
• A change in the direction of a POV control
• Loss of acquisition

Do not call the Win32 CloseHandle function on the event while it has been selected into a DirectInputDevice object. You must call this method with the hEvent parameter set to NULL before closing the event handle.

The event notification handle cannot be changed while the device is acquired. If the function is successful, the application can use the event handle like any other Win32 event handle.

The following code example checks whether the handle is currently set without blocking:

dwResult = WaitForSingleObject(hEvent, 0); 
if (dwResult == WAIT_OBJECT_0) { 
    // Event is set. If the event was created as 
    // autoreset, it has also been reset. 
} 

The following code example illustrates blocking indefinitely until the event is set. This behavior is strongly discouraged because the thread does not respond to the system until the wait is satisfied. In particular, the thread does not respond to Windows® messages.

dwResult = WaitForSingleObject(hEvent, INFINITE); 
if (dwResult == WAIT_OBJECT_0) { 
    // Event has been set. If the event was created 
    // as autoreset, it has also been reset. 
} 

The following code example illustrates a typical application loop for a non-message-based application that uses two events:.

HANDLE ah[2] = { hEvent1, hEvent2 }; 
 
while (TRUE) { 
 
    dwResult = MsgWaitForMultipleObjects(2, ah, FALSE, 
                        INFINITE, QS_ALLINPUT); 
    switch (dwResult) { 
    case WAIT_OBJECT_0: 
        // Event 1 has been set. If the event was created as
        // autoreset, it has also been reset. 
        ProcessInputEvent1(); 
        break; 
 
    case WAIT_OBJECT_0 + 1: 
        // Event 2 has been set. If the event was created as
        // autoreset, it has also been reset. 
        ProcessInputEvent2(); 
        break; 
 
    case WAIT_OBJECT_0 + 2: 
        // A Windows message has arrived. Process 
        // messages until there aren't any more. 
        while(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)){ 
            if (msg.message == WM_QUIT) { 
                goto exitapp; 
            } 
            TranslateMessage(&msg); 
            DispatchMessage(&msg); 
        } 
        break; 
 
    default: 
        // Unexpected error. 
        Panic(); 
        break; 
    } 
} 

The following code example illustrates a typical message loop for a message-based application that uses two events:

HANDLE ah[2] = { hEvent1, hEvent2 }; 
DWORD dwWait = 0; 
 
while (TRUE) { 
 
    dwResult = MsgWaitForMultipleObjects(2, ah, FALSE, 
                                         dwWait, QS_ALLINPUT); 
    dwWait = 0; 
 
    switch (dwResult) { 
    case WAIT_OBJECT_0: 
        // Event 1 has been set. If the event was 
        // created as autoreset, it has also 
        // been reset. 
        ProcessInputEvent1(); 
        break; 
 
    case WAIT_OBJECT_0 + 1: 
        // Event 2 has been set. If the event was 
        // created as autoreset, it has also 
        // been reset. 
        ProcessInputEvent2(); 
        break; 
 
    case WAIT_OBJECT_0 + 2: 
        // A Windows message has arrived. Process 
        // messages until there aren't any more. 
        while(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)){ 
            if (msg.message == WM_QUIT) { 
                goto exitapp; 
            } 
            TranslateMessage(&msg); 
            DispatchMessage(&msg); 
        } 
        break; 
 
    default: 
        // No input or messages waiting. 
        // Do a frame of the game. 
        // If the game is idle, tell the next wait 
        // to wait indefinitely for input or a message. 
        if (!DoGame()) { 
            dwWait = INFINITE; 
        } 
        break; 
    } 
} 

Requirements

  Windows NT/2000/XP: Requires Windows® 2000.
  Windows 98/Me: Requires Windows 98 or later. Available as a redistributable for Windows 98.
  Header: Declared in Dinput.h.

See Also

Polling and Event Notification