DirectInputCreateEx

The DirectInputCreateEx function creates a DirectInput object that supports the IDirectInput, IDirectInput2, or IDirectInput7 COM interfaces.

HRESULT WINAPI DirectInputCreateEx(
  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. Passing the version number of a previous version causes DirectInput to emulate that version. For more information, see Designing for Previous Versions of DirectInput.

riidltf

Unique identifier of the desired DirectInput interface. Values supported are IID_IDirectInput, IID_IDirectInput2, and IID_IDirectInput7. If UNICODE is defined during compilation, the Unicode version of the interface is returned; otherwise, it is the ANSI version.

ppvOut

Address of 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, rather than an IDirectInput interface, 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

Calling the function with punkOuter = NULL is equivalent to creating the object through CoCreateInstance(&CLSID_DirectInput, punkOuter, CLSCTX_INPROC_SERVER, &IID_IDirectInput7W, lplpDirectInput), then initializing it with IDirectInput7::Initialize.

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

There are separate ANSI and Unicode versions of this service. The ANSI version creates an object that supports the IDirectInputA interface, whereas the Unicode version creates an object that supports the IDirectInputW interface. As with other system services that are sensitive to character-set issues, macros in the header file map DirectInputCreateEx to the appropriate character set variation.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dinput.h.
  Import Library: Use dinput.lib.