IDirectInputDevice8::SetCooperativeLevel Method

  • Article

Establishes the cooperative level for this instance of the device. The cooperative level determines how this instance of the device interacts with other instances of the device and the rest of the system.

Syntax

HRESULT SetCooperativeLevel(
         HWND hwnd,
         DWORD dwFlags
)

Parameters

  • hwnd
    Window handle to be associated with the device. This parameter must be a valid top-level window handle that belongs to the process. The window associated with the device must not be destroyed while it is still active in a DirectInput device.
  • dwFlags
    Flags that describe the cooperative level associated with the device. The following flags are defined:
    • DISCL_BACKGROUND
      The application requires background access. If background access is granted, the device can be acquired at any time, even when the associated window is not the active window.
    • DISCL_EXCLUSIVE
      The application requires exclusive access. If exclusive access is granted, no other instance of the device can obtain exclusive access to the device while it is acquired. However, nonexclusive access to the device is always permitted, even if another application has obtained exclusive access. An application that acquires the mouse or keyboard device in exclusive mode should always unacquire the devices when it receives WM_ENTERSIZEMOVE and WM_ENTERMENULOOP messages. Otherwise, the user cannot manipulate the menu or move and resize the window.
    • DISCL_FOREGROUND
      The application requires foreground access. If foreground access is granted, the device is automatically unacquired when the associated window moves to the background.
    • DISCL_NONEXCLUSIVE
      The application requires nonexclusive access. Access to the device does not interfere with other applications that are accessing the same device.
    • DISCL_NOWINKEY
      Disable the Windows logo key. Setting this flag ensures that the user cannot inadvertently break out of the application. Note, however, that DISCL_NOWINKEY has no effect when the default action mapping user interface (UI) is displayed, and the Windows logo key will operate normally as long as that UI is present.

Return Value

If the method succeeds, the return value is DI_OK. If the method fails, the return value can be one of the following error values: DIERR_INVALIDPARAM, DIERR_NOTINITIALIZED, E_HANDLE.

Remarks

Applications must specify either DISCL_FOREGROUND or DISCL_BACKGROUND; it is an error to specify both or neither. Similarly, applications must specify either DISCL_EXCLUSIVE or DISCL_NONEXCLUSIVE.

If the system mouse is acquired in exclusive mode, the pointer is removed from the screen until the device is unacquired. This applies only to a mouse created by passing GUID_SysMouse to IDirectInput8::CreateDevice.

Applications that select the background exclusive mode cooperative level are not guaranteed to retain access to the device if another application requests exclusive access. When a background exclusive mode application loses access, calls to DirectInput device methods will fail and return DIERR_NOTACQUIRED. The application can regain access to the device by manually unacquiring the device and reaquiring it.

Applications must call this method before acquiring the device by using the IDirectInputDevice8 Interface method.

Requirements

Header: Declared in dinput.h.

See Also

Cooperative Levels