IDXCoreAdapterFactory::RegisterEventNotification method

Article
12/30/2021

Registers to receive notifications of specific conditions from a DXCore adapter or adapter list. For programming guidance, and code examples, see Using DXCore to enumerate adapters.

Syntax

virtual HRESULT STDMETHODCALLTYPE RegisterEventNotification(
  _In_ IUnknown *dxCoreObject,
  DXCoreNotificationType notificationType,
  _In_ PFN_DXCORE_NOTIFICATION_CALLBACK callbackFunction,
  _In_opt_ void *callbackContext,
  _Out_ uint32_t *eventCookie) = 0;

Parameters

dxCoreObject [in]

Type: IUnknown*

The DXCore object (IDXCoreAdapter or IDXCoreAdapterList) whose notifications you're subscribing to.

notificationType

Type: DXCoreNotificationType

The type of notification that you're registering for. See the table in DXCoreNotificationType for info about what types are valid with which kinds of objects.

callbackFunction [in]

Type: PFN_DXCORE_NOTIFICATION_CALLBACK

A pointer to a callback function (implemented by your application), which is called by the DXCore object for notification events. For the signature of the function, see PFN_DXCORE_NOTIFICATION_CALLBACK.

callbackContext [in]

Type: void*

An optional pointer to an object containing context info. This object is passed to your callback function when the notification is raised.

eventCookie [out]

Type: uint32_t*

A pointer to a uint32_t value. If successful, the function dereferences the pointer and sets the value to a non-zero cookie value representing this registration. Use this cookie value to unregister from the notification by calling IDXCoreAdapterFactory::UnregisterEventNotification. See Remarks.

If unsuccessful, the function dereferences the pointer and sets the value to zero, which represents an invalid cookie value.

Returns

Type: HRESULT

If the function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Return value	Description
DXGI_ERROR_INVALID_CALL	notificationType is unsupported by the operating system (OS).
E_INVALIDARG	`nullptr` was provided for dxCoreObject, or if an invalid notificationType and dxCoreObject combination was provided.
E_POINTER	`nullptr` was provided for either callbackFunction or eventCookie.

Remarks

You use RegisterEventNotification to register for events raised by IDXCoreAdapterList and IDXCoreAdapter interfaces. These notification types are supported.

DXCoreNotificationType	Supported dxCoreObject	Notes
AdapterListStale	IDXCoreAdapterList	Indicates that the list of adapters meeting your filter criteria has changed. If the adapter list is stale at the time of registration, then your callback is immediately called. This callback occurs at most one time per registration.
AdapterNoLongerValid	IDXCoreAdapter	Indicates that the adapter is no longer valid. If the adapter is invalid at registration time, then your callback is immediately called.
AdapterBudgetChange	IDXCoreAdapter	Indicates that a memory budgeting event has occurred, and that you should call IDXCoreAdapter::QueryState (with DXCoreAdapterState::AdapterMemoryBudget) to evaluate the current memory budget state. Upon registration, an initial callback will always occur to allow you to query the initial state.
AdapterHardwareContentProtectionTeardown	IDXCoreAdapter	Indicates that you should re-evaluate the current crypto session status; for example, by calling ID3D11VideoContext1::CheckCryptoSessionStatus to determine the impact of the hardware teardown for a specific ID3D11CryptoSession interface. Upon registration, an initial callback will always occur to allow you to query the initial state.

A call to the function that you provide in callbackFunction is made asynchronously on a background thread by DXCore when the detected event occurs. No guarantee is made as to the ordering or timing of callbacks—multiple callbacks may occur in any order, or even simultaneously. It's even possible for your callback to be invoked before RegisterEventNotification has completed. In that case, DXCore guarantees that your eventCookie is set before your callback is called. Multiple callbacks for a specific registration will be serialized in order.

Callbacks may occur at any time until you call UnregisterEventNotification, and it completes. Callbacks occur on their own threads, and you may make calls into the DXCore API on those threads, including UnregisterEventNotification. However, you must not release the last reference to the dxCoreObject on this thread.

Important

Before you destroy the DXCore object represented by the dxCoreObject argument passed to RegisterEventNotification, you must use the cookie value to unregister that object from notifications by calling IDXCoreAdapterFactory::UnregisterEventNotification. If you don't do that, then a fatal exception is raised when the situation is detected.