GameInput service interfaces

The GameInput service, which is installed with the GameInput redistributable on Windows PCs, exposes COM interfaces that trusted system components use to coordinate with GameInput. These interfaces are defined in GameInputService.idl. They aren't part of the GameInput API, and they aren't included in the GameInput NuGet package.

Note

Callers must run as the LocalSystem account; calls from any other account fail with E_ACCESSDENIED.

The interfaces are obtained by creating the GameInput service's COM class, CLSID_GameInputService ({B773D0F8-01F8-41E7-9F23-6871DA0AACFF}), with CLSCTX_LOCAL_SERVER, and then querying for the interface that you need.

IGameInputFocusWatcher

IID: {CEE41410-CF25-4B6A-A99D-4F313596DE89}

Lets a caller receive notifications when the input focus or the visible system overlays change in a Windows session.

interface IGameInputFocusWatcher : IUnknown
{
    HRESULT RegisterClient(
        UINT32 sessionId,
        IGameInputFocusWatcherClient* client,
        UINT64* token);

    HRESULT UnregisterClient(
        UINT64 token);
}
Method Description
RegisterClient Registers client to receive focus notifications for the Windows session sessionId, and returns a token that identifies the registration. The client is notified once with the current state before RegisterClient returns, and then each time the focused process or the overlay flags change.
UnregisterClient Removes the registration identified by token. Returns GAMEINPUT_E_FOCUS_WATCHER_CLIENT_NOT_FOUND (0x838AD028) if no such registration exists.

A registration is also removed automatically if the registering process exits, or if a call to the client fails or doesn't return in time.

IGameInputFocusWatcherClient

IID: {94CD1F3A-7B05-43D8-8C84-126DD11E7206}

Implemented by the caller to receive notifications from IGameInputFocusWatcher.

interface IGameInputFocusWatcherClient : IUnknown
{
    HRESULT NotifyFocusChange(
        UINT32 processId,
        OverlayFlags overlayFlags);
}
Method Description
NotifyFocusChange Called with the ID of the process that has input focus in the session, and the OverlayFlags that describe which system overlays are visible. Returning a failure code removes the registration.

IGameInputControllerVisibility

IID: {D03F0E66-0B90-4B57-AFA0-D5693D5722FA}

Hides a game controller from processes in a Windows session, so that only the processes allowed by a visibility policy can use it.

interface IGameInputControllerVisibility : IUnknown
{
    HRESULT HideController(
        GUID containerId,
        UINT32 sessionId,
        UINT32 exclusiveProcessId,
        UINT32 policyCount,
        const ControllerVisibilityPolicy* policy);

    HRESULT ShowController(
        GUID containerId,
        UINT32 sessionId);
}
Method Description
HideController Hides the controller identified by its PnP container ID, containerId, according to the policyCount entries in policy. The process exclusiveProcessId, which must run in session sessionId, always keeps access to the controller. If the policy has no fallback entry, a fallback entry that hides the controller is added, so an empty policy hides the controller from every process except exclusiveProcessId. If the call fails, the controller is left unchanged.
ShowController Makes a controller that was hidden by HideController visible again. Succeeds if the controller isn't hidden or is no longer connected.

A hidden controller is made visible again when the exclusive process exits. While session sessionId isn't the active session, the controller is visible, and the policy is reapplied when the session becomes active again.

ControllerVisibilityPolicy

One entry of a controller visibility policy that's passed to IGameInputControllerVisibility::HideController.

typedef struct
{
    BSTR imageName;
    BOOL hidden;
} ControllerVisibilityPolicy;
Member Description
imageName File name of the executable image that the entry applies to, such as game.exe. A null or empty name identifies the fallback entry, which applies to every image that doesn't have an entry of its own.
hidden TRUE to hide the controller from processes running this image; FALSE to leave it visible to them.

OverlayFlags

Identifies the system overlays that are visible in a session. Values can be combined.

typedef enum OverlayFlags
{
    OverlayFlagNone            = 0x00,
    OverlayFlagGameBar         = 0x01,
    OverlayFlagTaskView        = 0x02,
    OverlayFlagVirtualKeyboard = 0x04
} OverlayFlags;
Constant Description
OverlayFlagNone No system overlay is visible.
OverlayFlagGameBar The XBOX Game Bar is visible.
OverlayFlagTaskView Task View is visible.
OverlayFlagVirtualKeyboard The on-screen keyboard is visible.

AppLocalDeviceId

A 32-byte identifier for an input device that the GameInput service passes to its internal clients. It has the same size and layout as APP_LOCAL_DEVICE_ID.

typedef struct
{
    BYTE value0;
    // value1 through value30
    BYTE value31;
} AppLocalDeviceId;

Requirements

Interface definition: GameInputService.idl

Implemented by: GameInput service, installed with the GameInput redistributable

Supported platforms: Windows

See also

GameInput
GameInput sideloading

Version History

Redistributable Changes
4.0 Introduced.
  • Last updated on