IDirectInputDevice::SetEventNotification
The IDirectInputDevice::SetEventNotification method sets the event notification status. This method 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. DirectInput will use the Win32 SetEvent function on the handle when the state of the device changes. If the hEvent parameter is NULL, then notification is disabled.
The application may create the handle as either a manual-reset or automatic-reset event by using the Win32 CreateEvent function. If the event is created as an automatic-reset event, then the operating system will automatically reset the event once a wait has been satisfied. If the event is created as a manual-reset event, then it is the application's responsibility to call the Win32 ResetEvent function to reset it. DirectInput will not call the Win32 ResetEvent function for event notification handles. Most applications will 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 may be one of the following error values:
| DIERR_ACQUIRED |
| DIERR_HANDLEEXISTS |
| DIERR_INVALIDPARAM |
| DIERR_NOTINITIALIZED |
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, then the application can use the event handle in the same manner as any other Win32 event handle.
The following example checks if 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
// automatic-reset, then it has also been reset.
}
The following example illustrates blocking indefinitely until the event is set. Note that this behavior is strongly discouraged because the thread will not respond to the system until the wait is satisfied. In particular, the thread will not respond to Windows messages.
dwResult = WaitForSingleObject(hEvent, INFINITE);
if (dwResult == WAIT_OBJECT_0) {
// Event has been set. If the event was created
// as automatic-reset, then it has also been reset.
}
The following example illustrates a typical message loop for a 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
// automatic-reset, then it has also been reset.
ProcessInputEvent1();
break;
case WAIT_OBJECT_0 + 1:
// Event 2 has been set. If the event was created as
// automatic-reset, then 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 example illustrates a typical application loop for a non-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 automatic-reset, then it has also
// been reset.
ProcessInputEvent1();
break;
case WAIT_OBJECT_0 + 1:
// Event 2 has been set. If the event was
// created as automatic-reset, then 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, then tell the next wait
// to wait indefinitely for input or a message.
if (!DoGame()) {
dwWait = INFINITE;
}
break;
}
}
QuickInfo
Windows NT: Use version 5.0 or later.
Windows: Use Windows 95 OSR2 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in dinput.h.
Import Library: Use dinput.lib.
See Also