DirectInput8Create

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

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

Parameters

hinst

Instance handle to the application or 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 ActiveX® control embedded in a Web page that uses DirectInput must pass its own instance handle, and not the handle to the Web 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 0x0700. For earlier versions, use DirectInputCreateEx, which is in Dinput.lib.

riidltf

Unique identifier of the desired interface. For DirectX 8.0, 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 callers pass NULL. If aggregation is requested, the object returned in *ppvOut is a pointer to IUnknown, as required by COM aggregation.

Return Values

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:

Remarks

The DirectInput object created by this function is implemented in Dinput8d.dll. Versions of interfaces earlier than DirectX 8.0 cannot be obtained in this implementation. To use earlier versions, create the DirectInput object by using DirectInputCreate or DirectInputCreateEx, which are in Dinput.lib.

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

  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.
  Import Library: Use dinput8.lib.