DirectInput8Create Function

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

Syntax

HRESULT WINAPI 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 Component Object Model (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 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	The application was written for an unsupported prerelease version of DirectInput.
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_OLDDIRECTINPUTVERSION	The application requires a newer version of DirectInput.
DIERR_OUTOFMEMORY	The DirectInput subsystem couldn't allocate sufficient memory to complete the call. This value is equal to the E_OUTOFMEMORY standard COM return value.

Remarks

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

To create a DirectX 8.x interface with the DirectX 9.0 software development kit (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 DirectX 9.0 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 DirectX 9.0 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 DirectX 9.0 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.

Function Information

Header	dinput.h
Import library	dinput8.lib
Minimum operating systems	Windows 98