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:
| Barramento | Descrição |
|---|---|
| 1394 | Não fornece um endereço porque os endereços são voláteis. O padrão é 0xFFFFFFFF. |
| EISA | Número do slot (0-F). |
| IDE | Para um dispositivo IDE, o endereço contém a ID de destino e o LUN. Para um canal IDE, o endereço é zero ou um (0 = canal primário e 1 = canal secundário). |
| ISApnp | Não fornece um endereço. O padrão é 0xFFFFFFFF. |
| Pc Card (PCMCIA) | O número do soquete (normalmente 0x00 ou 0x40). |
| PCI | O número do dispositivo na palavra alta e o número da função na palavra baixa. |
| SCSI | A ID de destino. |
| USB | O número da porta. |
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 aumentar 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 de alta potência.
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 para o 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 para o 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 para o estado PowerDeviceD0 do estado PowerDeviceD3 . Defina como zero se o dispositivo não der suporte ao estado D3.
Comentários
Os motoristas de ônibus 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 de 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
| Requisito | Valor |
|---|---|
| Cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de