Función PoFxActivateComponent (wdm.h)

Artículo
08/08/2023

La rutina PoFxActivateComponent incrementa el recuento de referencias de activación en el componente especificado.

Sintaxis

void PoFxActivateComponent(
  [in] POHANDLE Handle,
  [in] ULONG    Component,
  [in] ULONG    Flags
);

Parámetros

[in] Handle

Identificador que representa el registro del dispositivo con el marco de administración de energía (PoFx). El controlador de dispositivo recibió anteriormente este identificador de la rutina PoFxRegisterDevice .

[in] Component

Índice que identifica el componente. Este parámetro es un índice en la matriz Components de la estructura PO_FX_DEVICE que el controlador de dispositivo usó para registrar el dispositivo con PoFx. Si la matriz Components contiene N elementos, los índices de componente oscilan entre 0 y N-1.

[in] Flags

Marcas de la operación de activación. Establezca este miembro en cero o en uno de los siguientes bits PO_FX_FLAG_XXX :

Estos dos bits de marca son mutuamente excluyentes. Para obtener más información, vea la sección Comentarios.

Valor	Significado
PO_FX_FLAG_BLOCKING 0x1	Haga que la condición cambie sincrónicamente. Si se establece esta marca, la rutina que solicita el cambio de condición no devuelve el control al controlador que realiza la llamada hasta que el hardware del componente completa la transición a la nueva condición. Esta marca solo se puede usar si el autor de la llamada se ejecuta en irQL < DISPATCH_LEVEL.
PO_FX_FLAG_ASYNC_ONLY 0x2	Haga que la condición cambie completamente asincrónica. Si se establece esta marca, se llama a la rutina de devolución de llamada del controlador que realiza la llamada desde un subproceso distinto del subproceso en el que se llama a la rutina que solicita el cambio de condición. Por lo tanto, la rutina que solicita el cambio de condición siempre devuelve de forma asincrónica sin esperar a que se complete la devolución de llamada.

Valor

Significado

PO_FX_FLAG_BLOCKING
0x1

Haga que la condición cambie sincrónicamente. Si se establece esta marca, la rutina que solicita el cambio de condición no devuelve el control al controlador que realiza la llamada hasta que el hardware del componente completa la transición a la nueva condición. Esta marca solo se puede usar si el autor de la llamada se ejecuta en irQL < DISPATCH_LEVEL.

PO_FX_FLAG_ASYNC_ONLY
0x2

Haga que la condición cambie completamente asincrónica. Si se establece esta marca, se llama a la rutina de devolución de llamada del controlador que realiza la llamada desde un subproceso distinto del subproceso en el que se llama a la rutina que solicita el cambio de condición. Por lo tanto, la rutina que solicita el cambio de condición siempre devuelve de forma asincrónica sin esperar a que se complete la devolución de llamada.

Valor devuelto

None

Observaciones

Para que un controlador de dispositivo pueda acceder a un componente de un dispositivo, el controlador primero debe llamar a PoFxActivateComponent para obtener una referencia de activación al componente. Si el componente aún no está en la condición activa, esta llamada inicia una transición de la condición inactiva a la condición activa. Cuando se completa esta transición, PoFx llama a la rutina ComponentActiveConditionCallback del controlador para notificar al controlador. El controlador puede acceder a los registros de hardware en un componente solo cuando el componente está en la condición activa.

Si el componente ya está en la condición activa cuando se llama a PoFxActivateComponent , no se requiere ninguna transición y no se llama a la rutina ComponentActiveConditionCallback .

Después de que un componente entre en la condición activa, permanece en la condición activa siempre que el controlador contenga una o varias referencias de activación en el componente. Para liberar una referencia de activación, el controlador llama a la rutina PoFxIdleComponent . Cuando el controlador libera la última referencia de activación en un componente, PoFxIdleComponent inicia una transición de la condición activa a la condición inactiva. Un componente que se encuentra en la condición de inactividad puede entrar potencialmente en un estado fx de bajo consumo.

Si flags = PO_FX_FLAG_BLOCKING, la llamada a PoFxActivateComponent es sincrónica. Si el componente ya está en la condición activa, la llamada incrementa el recuento de referencias de activación y devuelve sin esperar. De lo contrario, PoFxActivateComponent espera a que se devuelva hasta que el componente complete la transición a la condición activa. En este caso, si el componente aún no está en el estado F0 cuando se produce la llamada, PoFxActivateComponent llama a la rutina ComponentIdleStateCallback del controlador para iniciar la transición a F0. Una vez que el componente entra en el estado F0, PoFxActivateComponent llama a la rutina ComponentActiveConditionCallback del controlador para informar al controlador de que el componente está en la condición activa. Estas devoluciones de llamada se producen en el mismo subproceso que la llamada a PoFxActivateComponent y PoFxActivateComponent solo devuelve después de que se devuelva la devolución de llamada ComponentActiveConditionCallback .

Si flags = PO_FX_FLAG_ASYNC_ONLY, la llamada a PoFxActivateComponent es asincrónica. Si el componente ya está en la condición activa, la llamada incrementa el recuento de referencias de activación y devuelve. De lo contrario, PoFxActivateComponent programa las devoluciones de llamada ComponentIdleStateCallback (si es necesario) y ComponentActiveConditionCallback para que se produzcan en otro subproceso y, a continuación, devuelve sin esperar a que se produzca ninguna devolución de llamada. Las devoluciones de llamada se pueden producir antes o después de que PoFxActivateComponent devuelva. El controlador se basa en la devolución de llamada ComponentActiveConditionCallback para determinar cuándo el componente completa la transición a la condición activa.

El controlador puede establecer Flags = 0 para indicar que no importa si la llamada a PoFxActivateComponent es sincrónica o asincrónica. En este caso, PoFx decide si debe realizar la llamada sincrónica o asincrónica.

Es posible que dos o más rutas de acceso de código del mismo controlador necesiten acceder simultáneamente a un componente determinado. Las rutinas PoFxActivateComponent y PoFxIdleComponent usan recuentos de referencias de activación para permitir que las distintas partes del controlador mantengan de forma independiente el acceso al componente sin necesidad de que el controlador administre centralmente el acceso al componente.

PoFx mantiene un recuento de referencias de activación para cada componente de un dispositivo. Una llamada a PoFxActivateComponent incrementa este recuento en uno y una llamada a PoFxIdleComponent disminuye el recuento por uno. Cuando el recuento es distinto de cero, el componente está en la condición activa o está en proceso de cambiar a la condición activa. Un componente que tiene un recuento de cero está en la condición de inactividad o está en proceso de cambiar a la condición de inactividad.

Cuando una llamada a PoFxActivateComponent hace que el recuento de referencias de activación aumente de 0 a 1, PoFxActivateComponent inicia una transición de la condición inactiva a la condición activa. Cuando una llamada a PoFxIdleComponent hace que el recuento disminuya de 1 a 0, PoFxIdleComponent inicia una transición de la condición activa a la condición inactiva.

PoFx notifica al controlador cuando se produce una transición entre la condición activa y la condición inactiva. Una devolución de llamada ComponentActiveConditionCallback notifica al controlador de una transición a la condición activa y una devolución de llamada ComponentIdleConditionCallback notifica al controlador de una transición a la condición inactiva. Cuando una llamada a PoFxActivateComponent o PoFxIdleComponent simplemente incrementa o disminuye el recuento de referencias de activación sin provocar dicha transición, el controlador no recibe ninguna notificación.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 8.
Plataforma de destino	Universal
Encabezado	wdm.h
Library	Ntoskrnl.lib
Archivo DLL	Ntoskrnl.exe
IRQL	<= DISPATCH_LEVEL

Consulte también

ComponentActiveConditionCallback

ComponentIdleStateCallback

PO_FX_DEVICE

PoFxIdleComponent

PoFxRegisterDevice