estrutura DEVICE_CAPABILITIES (wdm.h)

Uma estrutura DEVICE_CAPABILITIES descreve as funcionalidades de PnP e de energia de um dispositivo. Essa estrutura é retornada em resposta a um IRP IRP_MN_QUERY_CAPABILITIES .

Sintaxe

typedef struct _DEVICE_CAPABILITIES {
  USHORT             Size;
  USHORT             Version;
  ULONG              DeviceD1 : 1;
  ULONG              DeviceD2 : 1;
  ULONG              LockSupported : 1;
  ULONG              EjectSupported : 1;
  ULONG              Removable : 1;
  ULONG              DockDevice : 1;
  ULONG              UniqueID : 1;
  ULONG              SilentInstall : 1;
  ULONG              RawDeviceOK : 1;
  ULONG              SurpriseRemovalOK : 1;
  ULONG              WakeFromD0 : 1;
  ULONG              WakeFromD1 : 1;
  ULONG              WakeFromD2 : 1;
  ULONG              WakeFromD3 : 1;
  ULONG              HardwareDisabled : 1;
  ULONG              NonDynamic : 1;
  ULONG              WarmEjectSupported : 1;
  ULONG              NoDisplayInUI : 1;
  ULONG              Reserved1 : 1;
  ULONG              WakeFromInterrupt : 1;
  ULONG              SecureDevice : 1;
  ULONG              ChildOfVgaEnabledBridge : 1;
  ULONG              DecodeIoOnBoot : 1;
  ULONG              Reserved : 9;
  ULONG              Address;
  ULONG              UINumber;
  DEVICE_POWER_STATE DeviceState[POWER_SYSTEM_MAXIMUM];
  SYSTEM_POWER_STATE SystemWake;
  DEVICE_POWER_STATE DeviceWake;
  ULONG              D1Latency;
  ULONG              D2Latency;
  ULONG              D3Latency;
} DEVICE_CAPABILITIES, *PDEVICE_CAPABILITIES;

Membros

Size

Especifica o tamanho da estrutura, em bytes. Esse campo é definido pelo componente que envia a solicitação de IRP_MN_QUERY_CAPABILITIES .

Version

Especifica a versão da estrutura, atualmente versão 1. Esse campo é definido pelo componente que envia a solicitação de IRP_MN_QUERY_CAPABILITIES .

DeviceD1

Especifica se o hardware do dispositivo dá suporte ao estado de energia D1. Os drivers não devem alterar esse valor.

DeviceD2

Especifica se o hardware do dispositivo dá suporte ao estado de energia D2. Os drivers não devem alterar esse valor.

LockSupported

Especifica se o dispositivo dá suporte ao bloqueio de dispositivo físico que impede a ejeção do dispositivo. Esse membro pertence à ejeção do dispositivo de seu slot, em vez de ejetar um pedaço de mídia removível do dispositivo.

EjectSupported

Especifica se o dispositivo dá suporte à ejeção de dispositivo controlada por software enquanto o sistema está no estado PowerSystemWorking . Esse membro pertence à ejeção do dispositivo de seu slot, em vez de ejetar um pedaço de mídia removível do dispositivo.

Removable

Especifica se o dispositivo pode ser removido dinamicamente de seu pai imediato. Se Removable for definido como TRUE, o dispositivo não pertencerá ao mesmo objeto físico que seu pai.

Por exemplo, se Removable for definido como TRUE para um dispositivo composto USB dentro de uma impressora multifuncional, o dispositivo composto não pertencerá ao objeto físico de seu pai imediato, como um hub USB dentro de um computador notebook.

Na maioria dos casos, o driver de barramento, não o driver de função, deve determinar o valor do parâmetro Removível do dispositivo. Para dispositivos USB, o driver do hub USB define o parâmetro Removível . Ele não deve ser modificado pelo driver de função.

Se Removable for definido como TRUE, o dispositivo será exibido no programa Desconectar ou Ejetar Hardware , a menos que SurpriseRemovalOK também esteja definido como TRUE.

DockDevice

Especifica se o dispositivo é um periférico de encaixe.

UniqueID

Especifica se a ID da instância do dispositivo é exclusiva em todo o sistema. Esse bit fica claro se a ID da instância é exclusiva somente dentro do escopo do barramento. Para obter mais informações, consulte Cadeias de caracteres de identificação do dispositivo.

SilentInstall

Especifica se Gerenciador de Dispositivos deve suprimir todas as caixas de diálogo de instalação; exceto as caixas de diálogo necessárias, como "nenhum driver compatível encontrado".

RawDeviceOK

Especifica se o driver do barramento subjacente poderá conduzir o dispositivo se não houver nenhum driver de função (por exemplo, dispositivos SCSI no modo de passagem). Esse modo de operação é chamado de modo bruto.

SurpriseRemovalOK

Especifica se o driver de função do dispositivo pode lidar com o caso em que o dispositivo é removido antes que o Windows possa enviar IRP_MN_QUERY_REMOVE_DEVICE para ele. Se SurpriseRemovalOK estiver definido como TRUE, o dispositivo poderá ser removido com segurança de seu pai imediato, independentemente do estado em que o driver está.

Por exemplo, um mouse USB padrão não mantém nenhum estado em seu hardware e, portanto, pode ser removido com segurança a qualquer momento. No entanto, um disco rígido externo cujo driver armazena em cache gravações na memória não pode ser removido com segurança sem primeiro permitir que o driver libere seu cache para o hardware.

Os drivers para dispositivos USB que dão suporte à remoção surpresa devem definir isso como TRUE somente quando o IRP estiver sendo passado de volta para a pilha do driver.

WakeFromD0

Especifica se o dispositivo pode responder a um sinal de ativação externo enquanto estiver no estado D0 . Os drivers não devem alterar esse valor.

WakeFromD1

Especifica se o dispositivo pode responder a um sinal de ativação externo enquanto estiver no estado D1. Os drivers não devem alterar esse valor.

WakeFromD2

Especifica se o dispositivo pode responder a um sinal de ativação externo enquanto estiver no estado D2. Os drivers não devem alterar esse valor.

WakeFromD3

Especifica se o dispositivo pode responder a um sinal de ativação externo enquanto estiver no estado D3. Os drivers não devem alterar esse valor.

HardwareDisabled

Quando definido, esse sinalizador especifica que o hardware do dispositivo está desabilitado.

O driver de barramento pai de um dispositivo ou um driver de filtro de barramento define esse sinalizador quando esse driver determina que o hardware do dispositivo está desabilitado.

O gerenciador PnP envia um IRP_MN_QUERY_CAPABILITIES IRP logo após um dispositivo ser enumerado e envia outro após o dispositivo ter sido iniciado. O gerenciador PnP verifica esse bit somente logo após o dispositivo ser enumerado. Depois que o dispositivo é iniciado, esse bit é ignorado.

NonDynamic

Reservado para uso futuro.

WarmEjectSupported

Reservado para uso futuro.

NoDisplayInUI

Não exiba o dispositivo na interface do usuário. Se esse bit for definido, o dispositivo nunca será exibido na interface do usuário, mesmo que o dispositivo esteja presente, mas não seja iniciado. Somente os motoristas de ônibus e os drivers de filtro de ônibus associados devem definir esse bit. (Consulte também o sinalizador PNP_DEVICE_DONT_DISPLAY_IN_UI na estrutura PNP_DEVICE_STATE .)

Reserved1

Reservado para uso do sistema.

WakeFromInterrupt

Indica se o driver ou ACPI é responsável por manipular o evento de ativação. Se definido, o driver é responsável por manipular o evento de ativação. A ACPI arma o dispositivo quando ele recebe um IRP IRP_MN_WAIT_WAKE, mas não conecta a interrupção, conclua o IRP para notificar a pilha do dispositivo de um evento de ativação.

SecureDevice

Indica se o dispositivo é um dispositivo seguro.

ChildOfVgaEnabledBridge

Para um dispositivo VGA, indica se a ponte pai tem o bit de decodificação da VGA definido.

DecodeIoOnBoot

Indica se o dispositivo tem a decodificação de E/S habilitada na inicialização.

Reserved

Reservado para uso do sistema.

Address

Especifica um endereço que indica onde o dispositivo está localizado em seu barramento subjacente.

A interpretação desse número é específica do ônibus. Se o endereço for desconhecido ou o motorista do ônibus não der suporte a um endereço, o motorista do ônibus deixará esse membro com o valor padrão de 0xFFFFFFFF.

A lista a seguir descreve as informações que determinados motoristas de ônibus armazenam no campo Endereço para seus dispositivos filho:

UINumber

Especifica um número associado ao dispositivo que pode ser exibido na interface do usuário.

Esse número normalmente é um número de slot percebido pelo usuário, como um número impresso ao lado do slot no quadro ou algum outro número que facilita a localização do dispositivo físico para o usuário. Para ônibus sem essa convenção ou quando o UINumber é desconhecido, o motorista do ônibus deixa esse membro com seu valor padrão de 0xFFFFFFFF.

DeviceState[POWER_SYSTEM_MAXIMUM]

Uma matriz de valores que indica o estado de energia do dispositivo mais alimentado que o dispositivo pode manter para cada estado de energia do sistema. O elemento DeviceState[PowerSystemWorking] da matriz corresponde ao estado do sistema S0. A entrada para PowerSystemUnspecified é reservada para uso do sistema.

As entradas nessa matriz são baseadas nos recursos do devnode pai. Como regra geral, um driver não deve alterar esses valores. No entanto, se necessário, um driver pode reduzir o valor, por exemplo, de PowerDeviceD1 para PowerDeviceD2.

Se o driver de barramento não conseguir determinar o estado de energia do dispositivo apropriado para um dispositivo enumerado raiz, ele definirá DeviceState[PowerSystemWorking] como PowerDeviceD0 e todas as outras entradas para PowerDeviceD3.

SystemWake

Especifica o estado de energia do sistema menos alimentado do qual o dispositivo pode sinalizar um evento de ativação. Um valor de PowerSystemUnspecified indica que o dispositivo não pode ativar o sistema.

Um motorista de ônibus pode obter essas informações de seu devnode pai.

Em geral, um driver não deve alterar esse valor. Se necessário, no entanto, um driver pode elevar o estado de energia, por exemplo, de PowerSystemHibernate para PowerSystemS1, para indicar que seu dispositivo não pode ativar o sistema de um estado de hibernação, mas pode de um estado de suspensão mais avançado.

DeviceWake

Especifica o estado de energia do dispositivo menos alimentado do qual o dispositivo pode sinalizar um evento de ativação. Um valor de PowerDeviceUnspecified indica que o dispositivo não pode sinalizar um evento de ativação.

D1Latency

Especifica a latência aproximada do pior caso do dispositivo, em unidades de 100 microssegundos, para retornar o dispositivo ao estado PowerDeviceD0 do estado PowerDeviceD1 . Defina como zero se o dispositivo não der suporte ao estado D1.

D2Latency

Especifica a latência aproximada do pior caso do dispositivo, em unidades de 100 microssegundos, para retornar o dispositivo ao estado PowerDeviceD0 do estado PowerDeviceD2 . Defina como zero se o dispositivo não der suporte ao estado D2.

D3Latency

Especifica a latência aproximada do pior caso do dispositivo, em unidades de 100 microssegundos, para retornar o dispositivo ao estado PowerDeviceD0 do estado PowerDeviceD3 . Defina como zero se o dispositivo não der suporte ao estado D3.

Comentários

Os motoristas de barramento definem os valores apropriados nessa estrutura em resposta a um IRP IRP_MN_QUERY_CAPABILITIES . Drivers de filtro de barramento, drivers de função e drivers de filtro podem alterar os recursos definidos pelo motorista do ônibus.

Os drivers que enviam uma solicitação IRP_MN_QUERY_CAPABILITIES devem inicializar os membros Size, Version, Address e UINumber dessa estrutura antes de enviar o IRP.

Para obter mais informações sobre como usar a estrutura de DEVICE_CAPABILITIES para descrever os recursos de energia de um dispositivo, consulte Reporting Device Power Capabilities.

Requisitos

Confira também

IRP_MN_QUERY_CAPABILITIES

PNP_DEVICE_STATE