IDirectInput::CreateDevice

The IDirectInput::CreateDevice method creates and initializes an instance of a device based on a given GUID.

HRESULT CreateDevice(
  REFGUID rguid,                               
  LPDIRECTINPUTDEVICE *lplpDirectInputDevice,  
  LPUNKNOWN pUnkOuter                          
);
 

Parameters

rguid
Reference to (C++) or address of (C) the instance GUID for the desired input device (see Remarks). The GUID is retrieved through the IDirectInput::EnumDevices method, or it can be one of the following predefined GUIDs:
GUID_SysKeyboard The default system keyboard.
GUID_SysMouse The default system mouse.

For the above GUID values to be valid, your application must define INITGUID before all other preprocessor directives at the beginning of the source file, or link to Dxguid.lib.

lplpDirectInputDevice
Address of the IDirectInputDevice interface pointer if successful.
pUnkOuter
Address of the controlling object's IUnknown interface for COM aggregation, or NULL if the interface is not aggregated. Most callers will pass NULL.

Return Values

If the method succeeds, the return value is DI_OK.

If the method fails, the return value may be one of the following:

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOINTERFACE
DIERR_NOTINITIALIZED
DIERR_OUTOFMEMORY

Remarks

In C++ the rguid parameter must be passed by reference; in C, which does not have pass-by-reference, it must be passed by address. The following is an example of a C++ call:

lpdi->CreateDevice(GUID_SysKeyboard, &pdev, NULL);
 

The following shows the same call in C:

lpdi->lpVtbl->CreateDevice(lpdi, &GUID_SysKeyboard, &pdev, NULL);
 

Calling this function with punkOuter = NULL is equivalent to creating the object via CoCreateInstance(&CLSID_DirectInputDevice, NULL, CLSCTX_INPROC_SERVER, riid, lplpDirectInputDevice) and then initializing it with Initialize.

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

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
  Windows CE: Unsupported.
  Header: Declared in dinput.h.
  Import Library: Use dinput.lib.