The semantics of version numbers are left to the manufacturer of the device. The only guarantee is that newer versions have larger numbers.

For compatibility with DirectX 3, it is also valid to pass a DIDEVCAPS_DX3 structure with the dwSize member initialized to sizeof(DIDEVCAPS_DX3).

The number of objects returned in the structure is the maximum number of objects that could be enumerated. However, all of these objects are not necessarily returned during a call to .

The and flags in the dwFlags parameter restrict enumeration to objects that meet all the criteria defined by the included flags. For all the other flags, an object is enumerated if it meets the criterion defined by any included flag in this category. For example, ( | ) restricts enumeration to force-feedback trigger objects, and ( | | ) restricts enumeration to buttons of any kind that can be used as effect triggers.

Applications should not rely on this method to determine whether certain keyboard keys or indicator lights are present, as these objects might be enumerated even though they are not present. Although the basic set of available objects can be determined from the device subtype, there is no reliable way of determining whether extra objects such as the menu key are available.

If rguidProp is set to , the dwHow member of the structure should only be set to when getting information about input controls, such as buttons or axes. Setting for other device objects such as a physical interface device (PID) or LED devices can lead to unpredictable results.

S_FALSE is always returned when is called with rguidProp set to , even if the method succeeds.

The scan codes reported in Microsoft DirectX 8.1 are different from the ones reported in DirectX 8.0. In DirectX 8.0, the property actually reported the single byte * constant associated with the key, not the scan code. In DirectX 8.1 and later releases, the property reports the make scan code as would be reported by a PS/2 keyboard. In some cases, scan codes are multiple bytes, in which case the scan code bytes are ordered with the first byte in the least significant byte of the DWORD retrieved by the property.

The following C example shows how to obtain the value of the property.

  dipdw;  //  contains a  structure. 	
             hr; 	
            dipdw.diph.dwSize       = sizeof(); 	
            dipdw.diph.dwHeaderSize = sizeof(); 	
            dipdw.diph.dwObj        = 0; // device property 	
            dipdw.diph.dwHow        = ;  hr = idirectinputdevice9_GetProperty(pdid, , &dipdw.diph); 	
            if (SUCCEEDED(hr)) {  // The dipdw.dwData member contains the buffer size. 	
            } 	
            

The following example shows how to extract the two WORD values from the dwData member of the structure using the property:

 wVendorID  = LOWORD(.dwData);	
            wProductID = HIWORD(.dwData);	
            

The buffer size determines the amount of data that the buffer can hold between calls to the method before data is lost. This value may be set to 0 to indicate that the application does not read buffered data from the device. If the buffer size in the dwData member of the structure is too large for the device to support it, then the largest possible buffer size is set.

Before a device can be acquired, a data format must be set by using the method or method. If the data format has not been set, Interface returns .

Devices must be acquired before calling the or methods for that device.

Device acquisition does not use a reference count. Therefore, if an application calls the Interface method twice, then calls the Interface method once, the device is unacquired.

If succeeds but no actions have been mapped, a subsequent call to will return but a call to Interface will fail with .

The data format must be set before the device can be acquired by using the Interface method. It is necessary to set the data format only once. The data format cannot be changed while the device is acquired.

If the application is using action mapping, the data format is set instead by the call to .

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

For compatibility with DirectX 3, it is also valid to pass a DIDEVICEOBJECTINSTANCE_DX3 structure with the dwSize member initialized to sizeof(DIDEVICEOBJECTINSTANCE_DX3).

For compatibility with DirectX 3, it is also valid to pass a DIDEVICEINSTANCE_DX3 structure with the dwSize member initialized to sizeof(DIDEVICEINSTANCE_DX3).

If this method fails, the underlying object should be considered to be in an indeterminate state and must be reinitialized before use.

If the return value is , the effect was created, and the parameters of the effect were updated, but the effect was not necessarily downloaded. For it to be downloaded, the device must be acquired in exclusive mode.

If the callback stops the enumeration prematurely, the enumeration is considered to have succeeded.

An application can use the dwEffType member of the DIEffectInfo structure to obtain general information about the effect, such as its type and which envelope and condition parameters are supported by the effect.

To exploit an effect to its fullest, contact the device manufacturer to obtain information about the semantics of the effect and its effect-specific parameters.

The device must be acquired at the exclusive cooperative level for this method to succeed.

The and flags may not always be reported correctly because there is no mechanism for the drivers to report that they support these flags.

The device must be acquired at the exclusive cooperative level for this method to succeed.

The results are unpredictable if you create or destroy an effect while an enumeration is in progress. However, the callback function can safely release the effect passed to it.

Other device-specific error codes are also possible. Ask the hardware manufacturer for details.

Because each driver implements different escapes, it is the application's responsibility to ensure that it is sending the escape to the correct driver by comparing the value of the guidFFDriver member of the structure against the value the application is expecting.

Before a device data can be polled, the data format must be set by using the or method, and the device must be acquired by using the Interface method.

Applications should not use . Force Feedback is the recommended way to send data to a device. If you want to send other data to a device, such as changing LED or internal device states, the HID application programming interface (API) is the recommended way.

If the callback stops the enumeration prematurely, the enumeration is considered to have succeeded.

The method returns if no mappings were created for the device. For example, a keyboard or mouse will not provide mappings for genre-specific actions.

If is returned, one or more of the mappings was not valid. The dwHow member of the structure is set to DIAH_ERROR. The application can iterate through the action map to find and correct errors.

If DIEFF_MAPFILEFAIL is returned, an error has occurred either reading the vendor supplied file for the device or reading or writing the user configuration file for the device.

> is returned if the mappings were not configurable. For example, the buttons on a voice controller cannot be reconfigured because each button causes a specific hardware action to occur. > overrides other success codes, so a check of the return codes will not reveal if any actions have been mapped.

If succeeds but no actions have been mapped, a subsequent call to will return but a call to Interface will fail with .

This method provides the mechanism to change action-to-control mapping from the device defaults. An application must use this method to map its in-game actions to virtual controls.

The user name passed to this method binds a set of action mappings for a device to a specific user. Settings are automatically saved to disk when they differ from the currently applied map. Applications that accept input from multiple users should be very careful when applying action maps to the system mouse or keyboard, as the action maps for each user may conflict.

The method can be called only when the device is not acquired.

If succeeds but no actions have been mapped, a subsequent call to will return but a call to Interface will fail with .

For compatibility with DirectX 3, it is also valid to pass a DIDEVCAPS_DX3 structure with the dwSize member initialized to sizeof(DIDEVCAPS_DX3).

The number of objects returned in the structure is the maximum number of objects that could be enumerated. However, all of these objects are not necessarily returned during a call to .

The data format must be set before the device can be acquired by using the Interface method. It is necessary to set the data format only once. The data format cannot be changed while the device is acquired.

If the application is using action mapping, the data format is set instead by the call to .

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

For compatibility with DirectX 3, it is also valid to pass a DIDEVICEINSTANCE_DX3 structure with the dwSize member initialized to sizeof(DIDEVICEINSTANCE_DX3).

Applications do not typically need to create a structure. An application can use one of the predefined global data format variables, c_dfDIMouse, c_dfDIMouse2, c_dfDIKeyboard, c_dfDIJoystick, or c_dfDIJoystick2.

Applications that need to create a structure must first call to determine the available objects for the current device. This is because the method will return if an object is described in the structure but does not exist on the current device.

The following code example sets a data format for a device that has an X-axis and a Y-axis:

 // Suppose an application uses the following 	
            // structure to read device data.  typedef struct MYDATA {  LONG  lX;                   // X-axis goes here.  LONG  lY;                   // Y-axis goes here.  BYTE  bButtonA;             // One button goes here.  BYTE  bButtonB;             // Another button goes here.  BYTE  bPadding[2];          // Must be DWORD multiple in size. 	
            } MYDATA;  // Then, it can use the following data format.  DIOBJECTDATAFORMAT rgodf[ ] = {  { &, FIELD_OFFSET(MYDATA, lX),  | , 0, },  { &, FIELD_OFFSET(MYDATA, lY),   | , 0, },  { &, FIELD_OFFSET(MYDATA, bButtonA),  | , 0, },  { &, FIELD_OFFSET(MYDATA, bButtonB),   | , 0, }, 	
            }; 	
            #define numObjects (sizeof(rgodf) / sizeof(rgodf[0]))   df = {  sizeof(),       // Size of this structure  sizeof(DIOBJECTDATAFORMAT), // Size of object data format  ,               // Absolute axis coordinates  sizeof(MYDATA),             // Size of device data  numObjects,                 // Number of objects  rgodf,                      // And here they are 	
            }; 

The buffer at lprgImageInfoArray must be large enough to hold all required image information structures. Applications can query for the required size by calling the method with the dwBufferSize member set to zero. After the call, dwBufferUsed contains the amount of memory, in bytes, that was modified.

The following device types and subtypes are defined for use in the dwDevType member.

• First-person action game device. The following subtypes are defined.

  • Device that does not provide the minimum number of device objects for action mapping.

  • Device designed for first-person shooter games.

  • Device with six degrees of freedom; that is, three lateral axes and three rotational axes.

  • Unknown subtype.

• Device that does not fall into another category.

• Input device used to control another type of device from within the context of the application. The following subtypes are defined.

  • Control used to make communications selections.

  • Device that must use its default configuration and cannot be remapped.

  • Unknown subtype.

• Device for steering. The following subtypes are defined.

  • Steering device that reports acceleration and brake pedal values from a single axis.

  • Steering device that reports acceleration and brake pedal values from separate axes.

  • Hand-held steering device.

  • Steering device that does not provide the minimum number of device objects for action mapping.

  • Steering device that reports acceleration, brake, and clutch pedal values from separate axes.

• Controller for flight simulation. The following subtypes are defined.

  • Flight controller that does not provide the minimum number of device objects for action mapping.

  • Flight device based on a remote control for model aircraft.

  • Joystick.

  • Yoke.

• Gamepad. The following subtypes are defined.

  • Gamepad that does not provide the minimum number of device objects for action mapping.

  • Standard gamepad that provides the minimum number of device objects for action mapping.

  • Gamepad that can report x-axis and y-axis data based on the attitude of the controller.

• Joystick. The following subtypes are defined.

  • Joystick that does not provide the minimum number of device objects for action mapping.

  • Standard joystick that provides the minimum number of device objects for action mapping.

• Keyboard or keyboard-like device. The following subtypes are defined.

  • Subtype could not be determined.

  • IBM PC/XT 83-key keyboard.

  • Olivetti 102-key keyboard.

  • IBM PC/AT 84-key keyboard.

  • IBM PC Enhanced 101/102-key or Microsoft Natural keyboard.

  • Nokia 1050 keyboard.

  • Nokia 9140 keyboard.

  • Japanese NEC PC98 keyboard.

  • Japanese NEC PC98 laptop keyboard.

  • Japanese NEC PC98 106-key keyboard.

  • Japanese 106-key keyboard.

  • Japanese AX keyboard.

  • Japanese J3100 keyboard.

• A mouse or mouse-like device (such as a trackball). The following subtypes are defined.

  • Mouse that returns absolute axis data.

  • Fingerstick.

  • Touchpad.

  • Trackball.

  • Traditional mouse.

  • Subtype could not be determined.

• Remote-control device. The following subtype is defined.

  • Subtype could not be determined.

• Screen reference. The following subtypes are defined.

  • Unknown subtype.

  • Light gun.

  • Light pen.

  • Touch screen.

• Specialized device with functionality unsuitable for the main control of an application, such as pedals used with a wheel. The following subtypes are defined.

  • Secondary handheld controller.

  • Device whose primary function is to report acceleration and brake pedal values from a single axis.

  • Device whose primary function is to report acceleration and brake pedal values from separate axes.

  • Device that tracks hand movement.

  • Device that tracks head movement.

  • Device with rudder pedals.

  • Device that reports gear selection from an axis.

  • Device that reports gear selection from button states.

  • Device whose primary function is to report at least two throttle values. It may have other controls.

  • Device whose primary function is to report acceleration, brake, and clutch pedal values from separate axes.

  • Device whose primary function is to report a single throttle value. It may have other controls.

  • Unknown subtype.

Versions of DirectInput earlier than DirectX 8.0 have a somewhat different scheme of device types and subtypes. See the DIDEVTYPExxx defines in Dinput.h.

Applications can use the wUsagePage and wUsage members to obtain additional information about how the object was designed to be used. For example, if wUsagePage has the value 0x02 (vehicle controls) and wUsage has the value 0xB9 (elevator trim), the object was designed to be the elevator trim control on a flight stick. A flight simulator application can use this information to provide more reasonable defaults for objects on the device. HID usage codes are determined by the USB standards committee.

Calling this method with pUnkOuter = null is equivalent to creating the object by CoCreateInstance (&CLSID_DirectInputDevice, null, CLSCTX_INPROC_SERVER, riid, lplpDirectInputDevice) and then initializing it with Initialize.

Calling this method with pUnkOuter != null is equivalent to creating the object by CoCreateInstance (&CLSID_DirectInputDevice, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInputDevice). The aggregated object must be initialized manually.

All installed devices can be enumerated, even if they are not present. For example, a flight stick might be installed on the system but not currently plugged into the computer. Set the dwFlags parameter to indicate whether only attached or all installed devices should be enumerated. If the flag is not present, all installed devices are enumerated.

A preferred device type can be passed as a dwDevType filter so that only the devices of that type are enumerated.

On Microsoft Windows XP, DirectInput enumerates only one mouse and one keyboard device, referred to as the system mouse and the system keyboard. These devices represent the combined output of all mice and keyboards respectively on a system. For information about how to read from multiple mice or keyboards individually on Windows XP, see the WM_INPUT documentation.

The keyboard and mouse are enumerated last.

The DirectInput object created by this function is implemented in Dinput8.dll. Versions of interfaces earlier than DirectX 8.0 cannot be obtained in this implementation.

To create a DirectX 8.x interface with the latest DirectX SDK without using CoCreateInstance:

1. Set "#define 0x0800" before the include statement for Dinput8.h.

2. Call DirectInput8Create instead of DirectInputCreateEx.

3. Link to the Dinput8.lib library instead of Dinput.lib.

To create a DirectX 8.x interface with the DirectX 8.x SDK without using CoCreateInstance:

1. Call DirectInput8Create instead of DirectInputCreateEx.

2. Link to the Dinput8.lib library instead of Dinput.lib.

To create a DirectX 7.0 interface from the DirectX 8.x or latest DirectX SDK without using CoCreateInstance:

1. Set "#define 0x0700" before the include statement for dinput.h.

2. Call DirectInputCreateEx instead of DirectInput8Create.

3. Link to the Dinput.lib library instead of Dinput8.lib.

To create a DirectX 7.0 interface from the DirectX 8.x or latest DirectX SDK using CoCreateInstance:

1. Call CoInitializeEx.

2. Call CoCreateInstance using CLISID_DirectInput.

3. Use IDirectInput7::Initialize to initialize the DirectInput object.

To create a DirectX 8.x or DirectX 9.0 interface from the DirectX 8.x or latest DirectX SDK using CoCreateInstance:

1. Call CoInitializeEx.

2. Call CoCreateInstance using CLISID_DirectInput8.

3. Use to initialize the DirectInput object.

Calling the function with pUnkOuter = null is equivalent to creating the object through CoCreateInstance( &CLSID_DirectInput8, punkOuter, CLSCTX_INPROC_SERVER, &IID_IDirectInput8W, lplpDirectInput), then initializing it with .

Calling the function with pUnkOuter != null is equivalent to creating the object through CoCreateInstance( &CLSID_DirectInput8, punkOuter, CLSCTX_INPROC_SERVER, &IID_IUnknown, lplpDirectInput). The aggregated object must be initialized manually.