Compartir a través de

Método IWDFDevice2::AssignS0IdleSettings (wudfddi.h)

  • Artículo

[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los controladores UMDF nuevos deben escribirse con UMDF 2. No se agregan nuevas características a UMDF 1 y hay compatibilidad limitada con UMDF 1 en versiones más recientes de Windows 10. Los controladores universales de Windows deben usar UMDF 2. Para obtener más información, consulta Introducción con UMDF.

El método AssignS0IdleSettings proporciona información proporcionada por el controlador que el marco usa cuando un dispositivo está inactivo y el sistema está en estado de funcionamiento (S0).

Sintaxis

HRESULT AssignS0IdleSettings(
  [in] WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps,
  [in] DEVICE_POWER_STATE                    DxState,
  [in] ULONG                                 IdleTimeout,
  [in] WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings,
  [in] WDF_TRI_STATE                         Enabled
);

Parámetros

[in] IdleCaps

Enumerador de tipo WDF_POWER_POLICY_S0_IDLE_CAPABILITIES que identifica la capacidad del dispositivo de reactivarse después de establecerse en un estado de bajo consumo, mientras que el sistema permanece en su estado de funcionamiento (S0).

[in] DxState

Enumerador con tipo DEVICE_POWER_STATE que identifica el estado de energía de dispositivo bajo que el dispositivo entrará después de que finalice el período de tiempo de espera de inactividad. DEVICE_POWER_STATE valores se definen en wdm.h.

[in] IdleTimeout

La cantidad de tiempo, en milisegundos, que el dispositivo permanecerá inactivo antes de que el marco lo coloque en el estado de baja potencia proporcionado por DxState. Para usar el valor de tiempo de espera de inactividad predeterminado del marco, especifique IdleTimeoutDefaultValue Para obtener más información, vea la sección Comentarios.

[in] UserControlOfIdleSettings

Enumerador con tipo WDF_POWER_POLICY_S0_IDLE_USER_CONTROL que indica si los usuarios tienen la capacidad de modificar la configuración inactiva del dispositivo.

[in] Enabled

Enumerador de tipo WDF_TRI_STATE que indica si el dispositivo se apagará si permanece inactivo y mientras la alimentación del sistema está en S0. Este miembro puede tener uno de los siguientes valores:

WdfTrue : el apagado está habilitado.

WdfFalse : el apagado está deshabilitado.

WdfUseDefault : el apagado se habilita inicialmente de forma predeterminada; pero si el parámetro UserControlOfIdleSettings se establece en IdleAllowUserControl, la configuración del usuario o el archivo INF del controlador invalida el valor inicial.

Si el apagado está habilitado, el dispositivo tiene una funcionalidad de reactivación y el valor de tiempo de espera de inactividad expira, el marco llama a la función de devolución de llamada IPowerPolicyCallbackWakeFromS0::OnArmWakeFromS0 antes de que el dispositivo entre en un estado de baja potencia.

Valor devuelto

AssignS0IdleSettings devuelve S_OK si la operación se realiza correctamente. De lo contrario, el método podría devolver uno de los siguientes valores:

Código devuelto Descripción
E_INVALIDARG
 El autor de la llamada especificó un valor no válido para un parámetro de entrada.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_REQUEST)
 El controlador de llamada no es el propietario de la directiva de energía del dispositivo.
HRESULT_FROM_NT(STATUS_POWER_STATE_INVALID)
 El parámetro DxState especifica un estado de alimentación del dispositivo no válido o el parámetro IdleCaps indica que el dispositivo puede reactivarse a sí mismo, pero el controlador de bus indica que el dispositivo no se puede reactivar.
 

Este método podría devolver uno de los otros valores que contiene Winerror.h.

Comentarios

La primera vez que un controlador llama a AssignS0IdleSettings, se producen las siguientes acciones:

  • El marco almacena los valores de todos los parámetros.
  • Si el parámetro UserControlOfIdleSettings se establece en IdleAllowUserControl y si el parámetro Enabled está establecido en WdfUseDefault, el marco lee el registro para averiguar si el usuario ha habilitado el encendido del dispositivo cuando está inactivo.
Durante las llamadas posteriores a AssignS0IdleSettings, el marco solo almacena los valores de los parámetros DxState, IdleTimeout y Enabled . Además, el marco almacena el valor del parámetro IdleCaps sujeto a las reglas siguientes:
  • Si el controlador ha especificado alguna vez IdleCanWakeFromS0 para el valor del parámetro IdleCaps en una llamada anterior a AssignS0IdleSettings, no podrá cambiar posteriormente ese valor a IdleUsbSelectiveSuspend.
  • Si el controlador ha especificado alguna vez IdleUsbSelectiveSuspend para el valor del parámetro IdleCaps en una llamada anterior a AssignS0IdleSettings, no podrá cambiar posteriormente ese valor a IdleCanWakeFromS0.

Las reglas siguientes se aplican al valor especificado para el parámetro DxState :

  • El valor no puede ser PowerDeviceD0.
  • En el caso de los dispositivos USB, el valor no puede ser PowerDeviceD0 o PowerDeviceD3.
  • Si especifica DevicePowerMaximum, el marco usa el valor que el controlador en modo kernel para el bus del dispositivo proporcionado en el miembro DeviceWake de su estructura WDF_DEVICE_POWER_CAPABILITIES .
  • Si el valor del parámetro IdleCaps es IdleCanWakeFromS0 o IdleUsbSelectiveSuspend, no puede especificar un estado de alimentación del dispositivo inferior al estado de alimentación del dispositivo en el miembro DeviceWake de la estructura WDF_DEVICE_POWER_CAPABILITIES del controlador de bus en modo kernel. (En otras palabras, si el valor deviceWake del controlador de bus es PowerDeviceD2, el valor dxState del controlador de función no puede ser PowerDeviceD3).
Si especifica IdleTimeoutDefaultValue para el parámetro IdleTimeout , el tiempo de espera tiene como valor predeterminado cinco segundos. Puede examinar la salida de las extensiones del depurador !wudfext.wudfdevice y !wudfext.umdevstacks para ver la configuración eficaz y las referencias de energía.

Para obtener información sobre las entradas del Registro que controlan las funcionalidades inactivas de un dispositivo, consulte User Control of Device Idle and Wake Behavior in UMDF (Control de usuario del comportamiento inactivo del dispositivo y reactivación en UMDF).

Para obtener más información sobre cómo admitir las funcionalidades inactivas de un dispositivo, consulte Compatibilidad con Power-Down inactivos en controladores basados en UMDF.

Ejemplos

El ejemplo de código siguiente se basa en la versión UMDF del ejemplo de tostadora. En el ejemplo se obtiene la interfaz IWDFDevice2 y, a continuación, se llama a AssignS0IdleSettings.

    IWDFDevice2 *pIWDFDevice2 = NULL;
    HRESULT hr;

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pIWDFDevice2);
    if (SUCCEEDED(hr)) 
    {
    //
    // The toaster device is virtual, so we tell the framework that the 
    // device cannot wake if it sleeps while the system is in S0. The device 
    // can return to D0 only when the driver stack receives an I/O request.
    //
    hr = pIWDFDevice2->AssignS0IdleSettings(IdleCannotWakeFromS0,
                                            PowerDeviceD3,
                                            IDLEWAKE_TIMEOUT_MSEC,
                                            IdleAllowUserControl,
                                            WdfTrue);
    }
...
    SAFE_RELEASE(pIWDFDevice2);

Requisitos

Requisito Value
Finalización del soporte técnico No disponible en UMDF 2.0 y versiones posteriores.
Plataforma de destino Escritorio
Versión mínima de UMDF 1,9
Encabezado wudfddi.h (incluya Wudfddi.h)
Archivo DLL WUDFx.dll

Consulte también

IWDFDevice2

IWDFDevice2::AssignSxWakeSettings

IWDFDevice3::AssignS0IdleSettingsEx