REQUEST_POWER_COMPLETE función de devolución de llamada (wdm.h)

Artículo
03/05/2024

La rutina de devolución de llamada de PowerCompletion completa el procesamiento de un IRP de energía.

Sintaxis

REQUEST_POWER_COMPLETE RequestPowerComplete;

void RequestPowerComplete(
  [in]           PDEVICE_OBJECT DeviceObject,
  [in]           UCHAR MinorFunction,
  [in]           POWER_STATE PowerState,
  [in, optional] PVOID Context,
  [in]           PIO_STATUS_BLOCK IoStatus
)
{...}

Parámetros

[in] DeviceObject

Puntero al DEVICE_OBJECT de destino para el IRP de energía completado.

[in] MinorFunction

Especifica el código de función secundaria en el IRP de energía. Para obtener más información, vea la lista de códigos IRP_MN_XXX admitidos en la sección Comentarios.

[in] PowerState

Especifica el estado de alimentación del dispositivo o el estado de alimentación del sistema que se pasó a la rutina PoRequestPowerIrp .

[in, optional] Context

Puntero al contexto que se pasó a PoRequestPowerIrp.

[in] IoStatus

Puntero a la estructura IO_STATUS_BLOCK del IRP completado.

Valor devuelto

None

Observaciones

Es posible que un controlador que envíe un IRP de energía necesite realizar tareas adicionales después de que todos los demás controladores hayan completado el IRP. Si es así, el controlador de envío debe registrar una rutina de devolución de llamada de PowerCompletion durante la llamada a la rutina PoRequestPowerIrp que asigna el IRP.

La rutina de devolución de llamada de PowerCompletion de un controlador solo se usa para IRP_MJ_POWER IRP que tienen códigos IRP menores de IRP_MN_SET_POWER, IRP_MN_QUERY_POWER y IRP_MN_WAIT_WAKE. Para obtener más información, consulte Envío de IRP_MN_QUERY_POWER o IRP_MN_SET_POWER para estados de energía del dispositivo y rutinas de devolución de llamada de espera/reactivación.

El administrador de E/S llama a la rutina powerCompletion del controlador de envío solo después de que el administrador de E/S haya llamado a todas las rutinas de IoCompletion establecidas por otros controladores a medida que pasaron el IRP a la pila. La rutina PowerCompletion realiza cualquier tarea adicional que el remitente del IRP requiera después de que todos los demás controladores hayan completado el IRP. La rutina PowerCompletion no debe liberar el IRP; el administrador de energía lo hace.

Se llama a la rutina PowerCompletion en IRQL = PASSIVE_LEVEL o IRQL = DISPATCH_LEVEL.

Ejemplos

Para definir una rutina de devolución de llamada de PowerCompletion , primero debe proporcionar una declaración de función que identifique el tipo de rutina de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una rutina de devolución de llamada de PowerCompletion denominada MyPowerCompletion, use el tipo REQUEST_POWER_COMPLETE como se muestra en este ejemplo de código:

REQUEST_POWER_COMPLETE MyPowerCompletion;

A continuación, implemente la rutina de devolución de llamada de la siguiente manera:

_Use_decl_annotations_
VOID
  MyPowerCompletion(
    PDEVICE_OBJECT DeviceObject,
    UCHAR MinorFunction,
    POWER_STATE PowerState,
    PVOID Context,
    PIO_STATUS_BLOCK IoStatus
    )
  {
      // Function body
  }

El tipo de función REQUEST_POWER_COMPLETE se define en el archivo de encabezado Wdm.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación a la _Use_decl_annotations_ definición de la función. La _Use_decl_annotations_ anotación garantiza que se usen las anotaciones que se aplican al tipo de función REQUEST_POWER_COMPLETE en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de roles de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Plataforma de destino	Escritorio
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Se llama en IRQL <= DISPATCH_LEVEL (consulte la sección Comentarios).