IDirectInputDevice8::SetEventNotification Method

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

Syntax

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 Win32?A target="_blank" HREF="http://msdn.microsoft.com/library/en-us/dllproc/synchro_8ub8.asp" TARGET="_top">CreateEvent function. If the event is created as an autoreset event, the operating system automatically resets the event when 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?A target="_blank" HREF="http://msdn.microsoft.com/library/en-us/dllproc/synchro_4f78.asp" TARGET="_top">ResetEvent function to reset it. DirectInput does not call the Win32?B>ResetEvent function for event notification handles. Most applications create the event as an automatic-reset event.

Return Value

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:

DIERR_ACQUIRED	The operation cannot be performed while the device is acquired.
DIERR_HANDLEEXISTS	The device already has an event notification associated with it. This value is equal to the E_ACCESSDENIED standard Component Object Model (COM) return value.
DIERR_INVALIDPARAM	An invalid parameter was passed to the returning function, or the object was not in a state that permitted the function to be called. This value is equal to the E_INVALIDARG standard COM return value.
DIERR_NOTINITIALIZED	The object has not been initialized.

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?A target="_blank" HREF="http://msdn.microsoft.com/library/en-us/sysinfo/handobj_289x.asp" TARGET="_top">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.

Examples

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 Microsoft 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; 
    } 
} 

See Also

Polling and Event Notification