PO_FX_POWER_CONTROL_CALLBACK función de devolución de llamada (wdm.h)
La rutina de devolución de llamada PowerControlCallback realiza una operación de control de energía solicitada por el marco de administración de energía (PoFx).
Sintaxis
PO_FX_POWER_CONTROL_CALLBACK PoFxPowerControlCallback;
NTSTATUS PoFxPowerControlCallback(
PVOID DeviceContext,
[in] LPCGUID PowerControlCode,
[in, optional] PVOID InBuffer,
[in] SIZE_T InBufferSize,
[out, optional] PVOID OutBuffer,
[in] SIZE_T OutBufferSize,
[out, optional] PSIZE_T BytesReturned
)
{...}
Parámetros
DeviceContext
[in] PowerControlCode
Puntero al código de control de energía. Este código es un valor GUID que especifica la operación solicitada.
[in, optional] InBuffer
Puntero al búfer que contiene los datos de entrada de la operación. El formato de los datos de este búfer depende del código de control de energía especificado por el parámetro PowerControlCode . El parámetro InBuffer es opcional y se puede especificar como NULL si la operación especificada no requiere datos de entrada.
[in] InBufferSize
Tamaño, en bytes, del búfer de entrada al que apunta el parámetro InBuffer . Si InBuffer es NULL, este parámetro es cero.
[out, optional] OutBuffer
Puntero al búfer en el que la rutina de devolución de llamada escribe los datos de salida de la operación. El formato de los datos de este búfer depende del código de control de energía especificado por el parámetro PowerControlCode . El parámetro OutBuffer es opcional y se puede especificar como NULL si la operación especificada no genera datos de salida.
[in] OutBufferSize
Tamaño, en bytes, del búfer de salida al que apunta el parámetro OutBuffer . Si OutBuffer es NULL, este parámetro es cero.
[out, optional] BytesReturned
Puntero a una ubicación en la que la rutina escribe el número de bytes de datos escritos en el búfer al que apunta OutBuffer. El número de bytes escritos debe ser menor o igual que OutBufferSize. Este parámetro es opcional y se puede especificar como NULL si el autor de la llamada no necesita saber cuántos bytes se escribieron en el búfer de salida.
Valor devuelto
La rutina PowerControlCallback devuelve STATUS_SUCCESS si la llamada se realiza correctamente. De lo contrario, devuelve un código de error adecuado.
Comentarios
PoFx llama a esta rutina para enviar una solicitud de control de energía directamente al controlador del dispositivo. Una solicitud de control de energía es similar a una solicitud de control de E/S (IOCTL). A diferencia de un IOCTL, sin embargo, una solicitud de control de energía se envía directamente al controlador y no se observa mediante otros controladores de dispositivos en la pila de dispositivos. Durante una llamada a PowerControlCallback , el controlador realiza de forma sincrónica la operación solicitada.
Esta rutina es opcional. No es necesario un controlador de dispositivo que no admita operaciones de control de energía para implementar una rutina PowerControlCallback .
El controlador de dispositivo puede llamar a la rutina PoFxPowerControl para enviar una solicitud de control de energía a PoFx.
Para obtener más información sobre las solicitudes de control de energía, consulte PoFxPowerControl.
Ejemplos
Para definir una rutina de devolución de llamada de PowerControlCallback , 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 Análisis de código para controladores, Comprobador de controladores estáticos (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 PowerControlCallback denominada MyPowerControlCallback, use el tipo PO_FX_POWER_CONTROL_CALLBACK, como se muestra en este ejemplo de código:
PO_FX_POWER_CONTROL_CALLBACK MyPowerControlCallback;
A continuación, implemente la rutina de devolución de llamada de la siguiente manera:
_Use_decl_annotations_
NTSTATUS
MyPowerControlCallback(
PVOID Context,
LPCGUID PowerControlCode,
PVOID InBuffer,
SIZE_T InBufferSize,
PVOID OutBuffer,
SIZE_T OutBufferSize,
PSIZE_T BytesReturned
)
{
// Function body
}
El tipo de función PO_FX_POWER_CONTROL_CALLBACK 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 PO_FX_POWER_CONTROL_CALLBACK 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 rol de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, vea Anotación del comportamiento de la función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Se admite a partir de Windows 8. |
| Plataforma de destino | Escritorio |
| Encabezado | wdm.h (incluya Wudfwdm.h) |
| IRQL | Se llama en IRQL <= DISPATCH_LEVEL. |