Função UrsSetPoHandle (ursdevice.h)

Artigo
02/07/2025

Registra e exclui o registro do driver cliente com a PoFx (estrutura de gerenciamento de energia).

Sintaxe

void UrsSetPoHandle(
  [in] WDFDEVICE Device,
  [in] POHANDLE  PoHandle
);

Parâmetros

[in] Device

Um identificador para o objeto de dispositivo da estrutura que o driver cliente recuperou na chamada anterior para WdfDeviceCreate.

[in] PoHandle

Um identificador que representa o registro do dispositivo com PoFx. O driver cliente recebe esse identificador do WDF no EvtDeviceWdmPostPoFxRegisterDevice e EvtDeviceWdmPrePoFxUnregisterDevice funções de retorno de chamada.

Valor de retorno

Nenhum

Observações

O driver do cliente para o controlador de função dupla deve ser o proprietário da política de energia. O driver pode receber notificações da PoFx (estrutura de gerenciamento de energia). Para fazer isso, depois de chamar UrsDeviceInitialize, o driver deve registrar funções de retorno de chamada PoFx. O driver cliente registra o dispositivo diretamente com a estrutura de energia ou obtém um POHANDLE do WDF no EvtDeviceWdmPostPoFxRegisterDevice. Depois que o registro for bem-sucedido, o driver fornecerá esse identificador para a extensão de classe de função dupla USB.

Na implementação do driver cliente da função de retorno de chamada EvtDeviceWdmPostPoFxRegisterDevice, espera-se que o driver chame UrsSetPoHandle passando o identificador recebido. Em algumas plataformas, a extensão de classe pode usar o POHANDLE para gerenciar o controlador. Por outro lado, antes que a extensão de classe exclua o registro com a estrutura de energia, ela invoca o do driver cliente EvtDeviceWdmPrePoFxUnregisterDevice implementação. Espera-se que o driver chame ursSetPoHandle passando NULL como o valor PoHandle.

Exemplos



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);
}

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 10
servidor com suporte mínimo	Windows Server 2016
da Plataforma de Destino	Windows
versão mínima do KMDF	1.15
cabeçalho	ursdevice.h (inclua Urscx.h)
biblioteca	Urscxstub.lib
IRQL	PASSIVE_LEVEL

Consulte também

EvtDeviceWdmPostPoFxRegisterDevice

EvtDeviceWdmPrePoFxUnregisterDevice

Partilhar via