DirectInput8Create

  • Article

Creates a DirectInput object and returns an IDirectInput8 Interface or later interface.

Syntax

HRESULT DirectInput8Create(
         HINSTANCE hinst,
         DWORD dwVersion,
         REFIID riidltf,
         LPVOID * ppvOut,
         LPUNKNOWN punkOuter
)

Parameters

  • hinst
    Instance handle to the application or dynamic-link library (DLL) that is creating the DirectInput object. DirectInput uses this value to determine whether the application or DLL has been certified and to establish any special behaviors that might be necessary for backward compatibility. It is an error for a DLL to pass the handle to the parent application. For example, an Microsoft ActiveX control embedded in a Web page that uses DirectInput must pass its own instance handle, and not the handle to the browser. This ensures that DirectInput recognizes the control and can enable any special behaviors that might be necessary.
  • dwVersion
    Version number of DirectInput for which the application is designed. This value is normally DIRECTINPUT_VERSION. If the application defines DIRECTINPUT_VERSION before including Dinput.h, the value must be greater than 0x0800. For earlier versions, use DirectInputCreateEx, which is in Dinput.lib.
  • riidltf
    Unique identifier of the desired interface. This value is IID_IDirectInput8A or IID_IDirectInput8W. Passing the IID_IDirectInput8 define selects the ANSI or Unicode version of the interface, depending on whether UNICODE is defined during compilation.
  • ppvOut
    Address of a pointer to a variable to receive the interface pointer if the call succeeds.
  • punkOuter
    Pointer to the address of the controlling object's IUnknown interface for COM aggregation, or NULL if the interface is not aggregated. Most calling applications pass NULL. If aggregation is requested, the object returned in ppvOut is a pointer to IUnknown, as required by COM aggregation.

Return Value

If the function succeeds, the return value is DI_OK. If the function fails, the return value can be one of the following error values: DIERR_BETADIRECTINPUTVERSION, DIERR_INVALIDPARAM, DIERR_OLDDIRECTINPUTVERSION, DIERR_OUTOFMEMORY.

Remarks

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 DIRECTINPUT_VERSION 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 DIRECTINPUT_VERSION 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 IDirectInput8::Initialize 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 IDirectInput8::Initialize.

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.

Requirements

Header: Declared in dinput.h.