nf-ursdevice-urssetpohandle.md

UID	title	description	old-location	tech.root	ms.date	keywords	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	f1_keywords	topic_type	api_type	api_location	api_name
NF:ursdevice.UrsSetPoHandle	UrsSetPoHandle function (ursdevice.h)	Registers and deletes the client driver's registration with the power management framework (PoFx).	buses\urssetpohandle.htm	usbref	05/07/2018	UrsSetPoHandle function	UrsSetPoHandle, UrsSetPoHandle function [Buses], buses.urssetpohandle, ursdevice/UrsSetPoHandle	ursdevice.h	Urscx.h	Windows	Windows 10	Windows Server 2016	1.15									Urscxstub.lib		PASSIVE_LEVEL	Windows		UrsSetPoHandle ursdevice/UrsSetPoHandle	APIRef kbSyntax	LibDef	Urscxstub.lib Urscxstub.dll	UrsSetPoHandle

UrsSetPoHandle function

-description

Registers and deletes the client driver's registration with the power management framework (PoFx).

-parameters

-param Device [in]

A handle to the framework device object that the client driver retrieved in the previous call to WdfDeviceCreate.

-param PoHandle [in]

A handle that represents the registration of the device with PoFx. The client driver receives this handle from WDF in EvtDeviceWdmPostPoFxRegisterDevice and EvtDeviceWdmPrePoFxUnregisterDevice callback functions.

-remarks

The client driver for the dual-role controller must be the power policy owner. The driver can receive notifications from the power management framework (PoFx). To do so, after calling UrsDeviceInitialize, the driver must register PoFx callback functions. The client driver registers the device with the power framework directly or obtains a POHANDLE from WDF in EvtDeviceWdmPostPoFxRegisterDevice. After registration is successful, the driver provides that handle to the USB dual-role class extension.

In the client driver's implementation of the EvtDeviceWdmPostPoFxRegisterDevice callback function, the driver is expected to call UrsSetPoHandle by passing the received handle. On some platforms, the class extension might use the POHANDLE to power-manage the controller. Conversely, before the class extension deletes the registration with the power framework, it invokes the client driver's EvtDeviceWdmPrePoFxUnregisterDevice implementation. The driver is expected to call UrsSetPoHandle by passing NULL as the PoHandle value.

Examples

EVT_WDFDEVICE_WDM_POST_PO_FX_REGISTER_DEVICE EvtDevicePostPoFxRegister;

EVT_WDFDEVICE_WDM_PRE_PO_FX_UNREGISTER_DEVICE EvtDevicePrePoFxUnregister;


EvtDriverDeviceAdd (
    _In_ WDFDRIVER Driver,
    _Inout_ PWDFDEVICE_INIT DeviceInit
    )
{
...

    WDFDEVICE device;
    NTSTATUS status;
...

    WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS idleSettings;
    WDF_POWER_FRAMEWORK_SETTINGS poFxSettings;
...
 
    TRY {

        WDF_POWER_FRAMEWORK_SETTINGS_INIT(&poFxSettings);
        poFxSettings.EvtDeviceWdmPostPoFxRegisterDevice = EvtDevicePostPoFxRegister;
        poFxSettings.EvtDeviceWdmPrePoFxUnregisterDevice = EvtDevicePrePoFxUnregister;

        status = WdfDeviceWdmAssignPowerFrameworkSettings(device, &poFxSettings);
        if (!NT_SUCCESS(status)) {
            // WdfDeviceWdmAssignPowerFrameworkSettings failed.

        }

        WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_INIT(&idleSettings, IdleCannotWakeFromS0);
        idleSettings.IdleTimeoutType = SystemManagedIdleTimeout;

        status = WdfDeviceAssignS0IdleSettings(device, &idleSettings);
        if (!NT_SUCCESS(status)) {
            // WdfDeviceAssignS0IdleSettings failed.

        }

    } FINALLY {
    }

..

}

NTSTATUS
EvtDevicePostPoFxRegister (
    _In_ WDFDEVICE Device,
    _In_ POHANDLE PoHandle
    )
{
    UrsSetPoHandle(Device, PoHandle);

    return STATUS_SUCCESS;
}


VOID
EvtDevicePrePoFxUnregister (
    _In_ WDFDEVICE Device,
    _In_ POHANDLE PoHandle
    )
{
    UNREFERENCED_PARAMETER(PoHandle);

    UrsSetPoHandle(Device, NULL);
}

-see-also

EvtDeviceWdmPostPoFxRegisterDevice

EvtDeviceWdmPrePoFxUnregisterDevice