estrutura DEVICE_OBJECT (wdm.h)
A estrutura DEVICE_OBJECT é usada pelo sistema operacional para representar um objeto de dispositivo. Um objeto de dispositivo representa um dispositivo lógico, virtual ou físico para o qual um driver lida com solicitações de E/S.
Sintaxe
typedef struct _DEVICE_OBJECT {
CSHORT Type;
USHORT Size;
LONG ReferenceCount;
struct _DRIVER_OBJECT *DriverObject;
struct _DEVICE_OBJECT *NextDevice;
struct _DEVICE_OBJECT *AttachedDevice;
struct _IRP *CurrentIrp;
PIO_TIMER Timer;
ULONG Flags;
ULONG Characteristics;
__volatile PVPB Vpb;
PVOID DeviceExtension;
DEVICE_TYPE DeviceType;
CCHAR StackSize;
union {
LIST_ENTRY ListEntry;
WAIT_CONTEXT_BLOCK Wcb;
} Queue;
ULONG AlignmentRequirement;
KDEVICE_QUEUE DeviceQueue;
KDPC Dpc;
ULONG ActiveThreadCount;
PSECURITY_DESCRIPTOR SecurityDescriptor;
KEVENT DeviceLock;
USHORT SectorSize;
USHORT Spare1;
struct _DEVOBJ_EXTENSION *DeviceObjectExtension;
PVOID Reserved;
} DEVICE_OBJECT, *PDEVICE_OBJECT;
Membros
Type
Usado pelo sistema operacional para indicar que um objeto é um objeto de dispositivo. Para objetos de dispositivo, o valor desse membro é 3. Este é um membro somente leitura.
Size
Especifica o tamanho, em bytes, do objeto do dispositivo. Esse tamanho inclui a extensão de dispositivo especificada pelo driver apontada pelo membro DeviceExtension , mas não inclui a extensão de objeto de dispositivo opaco apontada pelo membro DeviceObjectExtension . Size é um membro somente leitura.
ReferenceCount
Usado pelo gerenciador de E/S para acompanhar o número de identificadores abertos para o dispositivo associado ao objeto do dispositivo. Isso permite que o gerente de E/S evite descarregar um driver quando houver identificadores pendentes para os dispositivos do driver. Este é um membro somente leitura.
DriverObject
Um ponteiro para o objeto driver (DRIVER_OBJECT), que representa a imagem carregada do driver que foi inserido nas rotinas DriverEntry e AddDevice . Esse membro é definido pelo gerente de E/S após uma chamada bem-sucedida para IoCreateDevice ou IoCreateDeviceSecure. Este é um membro somente leitura.
NextDevice
Um ponteiro para o próximo objeto de dispositivo, se houver, que foi criado pelo mesmo driver. O gerente de E/S atualiza essa lista em cada chamada bem-sucedida para IoCreateDevice ou IoCreateDeviceSecure.
Um driver PnP (não Plug and Play) que está sendo descarregado deve percorrer ("walk") a lista de seus objetos de dispositivo e excluí-los. Um driver PnP não precisa percorrer essa lista de objetos de dispositivo. Em vez disso, os drivers PnP executam a limpeza durante a operação PnP de remoção do dispositivo (IRP_MN_REMOVE_DEVICE).
Um driver que recria seus objetos de dispositivo dinamicamente também usa esse membro. Este é um membro de leitura/gravação.
AttachedDevice
Um ponteiro para o objeto de dispositivo anexado. Se não houver nenhum objeto de dispositivo anexado, esse membro será NULL. O objeto de dispositivo apontado pelo membro AttachedDevice normalmente é o objeto de dispositivo de um driver de filtro, que intercepta solicitações de E/S originalmente direcionadas ao dispositivo representado pelo objeto do dispositivo. Para obter mais informações, consulte os tópicos IoAttachDevice e IoAttachDeviceByPointer . Este é um membro opaco.
CurrentIrp
Um ponteiro para o IRP atual se o driver tiver uma rotina StartIo cujo ponto de entrada foi definido no objeto driver e se o driver estiver processando IRP(s) no momento. Caso contrário, esse membro será NULL. Para obter mais informações, consulte os tópicos IoStartPacket e IoStartNextPacket . Este é um membro somente leitura.
Timer
Um ponteiro para um objeto de temporizador. Isso permite que o gerente de E/S chame uma rotina de temporizador fornecida pelo driver a cada segundo. Para obter mais informações, consulte IoInitializeTimer. Este é um membro de leitura/gravação.
Flags
Os drivers de dispositivo executam uma operação OR bit a bit com esse membro em seus objetos de dispositivo recém-criados usando um ou mais dos seguintes valores definidos pelo sistema.
Para obter mais informações sobre como definir o membro Flags , consulte Inicializando um objeto de dispositivo.
| Valor | Significado |
|---|---|
| DO_VERIFY_VOLUME (0x00000002) | Os drivers de mídia removível definem esse sinalizador enquanto processam solicitações de transferência. Esses drivers também devem marcar para esse sinalizador no destino de uma solicitação de transferência antes de transferirem dados. Para obter mais informações, consulte o tópico Suporte à Mídia Removível . |
| DO_BUFFERED_IO (0x00000004) | Especifica o tipo de buffer usado pelo gerenciador de E/S para solicitações de E/S enviadas para a pilha do dispositivo. Drivers de nível superior OU esse membro com o mesmo valor que o driver mais baixo na pilha, exceto possivelmente para drivers de nível mais alto. |
| DO_EXCLUSIVE (0x00000008) | Indica que o driver atende a um dispositivo exclusivo, como um dispositivo de vídeo, serial, paralelo ou de som. Os drivers WDM não devem definir esse sinalizador. Para obter mais informações, consulte o tópico Especificando o acesso exclusivo a objetos de dispositivo . |
| DO_DIRECT_IO (0x00000010) | Consulte DO_BUFFERED_IO. |
| DO_MAP_IO_BUFFER (0x00000020) | Esse sinalizador não é mais usado. Os drivers não devem definir esse sinalizador. |
| DO_DEVICE_INITIALIZING (0x00000080) | O gerenciador de E/S define esse sinalizador quando cria o objeto do dispositivo. Um driver de função de dispositivo ou driver de filtro limpa o sinalizador em sua rotina AddDevice , depois dele: (1) Anexa o objeto do dispositivo à pilha do dispositivo. (2) Estabelece o estado de energia do dispositivo. (3) Executa uma operação OR bit a bit no membro com um dos sinalizadores de energia (se necessário). O gerenciador de Plug and Play (PnP) verifica se o sinalizador está limpo após o retorno da rotina AddDevice. |
| DO_SHUTDOWN_REGISTERED (0x00000800) | Usado pelo gerente de E/S para indicar que um driver registrou o objeto do dispositivo para notificações de desligamento. Esse sinalizador não deve ser usado por drivers. |
| DO_BUS_ENUMERATED_DEVICE (0x00001000) | O sistema operacional define esse sinalizador em cada PDO (objeto de dispositivo físico). Os drivers não devem modificar esse sinalizador. |
| DO_POWER_PAGABLE (0x00002000) | Drivers pagináveis compatíveis com o Microsoft Windows 2000 e versões posteriores do Windows não fazem parte do caminho de paginação e não exigem inrush current devem definir esse sinalizador. O sistema chama esses drivers em IRQL = PASSIVE_LEVEL. Os drivers não podem definir esse sinalizador e DO_POWER_INRUSH. Todos os drivers para WDM, Microsoft Windows 98 e Windows Millennium Edition devem definir DO_POWER_PAGABLE. |
| DO_POWER_INRUSH (0x00004000) | Drivers de dispositivos que exigem inrush atual quando o dispositivo está ativado devem definir esse sinalizador. Um driver não pode definir esse sinalizador e DO_POWER_PAGABLE. |
| DO_DEVICE_TO_BE_RESET (0x04000000) | O gerente de E/S define esse sinalizador como um sinal para o motorista do ônibus redefinir o dispositivo. Outros drivers não devem usar esse sinalizador. |
| DO_DAX_VOLUME (0x10000000) | Indica que um volume é um volume DAX. |
Characteristics
Especifica uma ou mais constantes definidas pelo sistema, combinadas com uma operação OR bit a bit, que fornecem informações adicionais sobre o dispositivo do driver. Essas constantes incluem o seguinte:
| Valor | Significado |
|---|---|
| FILE_AUTOGENERATED_DEVICE_NAME | Direciona o gerente de E/S para gerar um nome para o dispositivo, em vez de o chamador especificar um DeviceName quando ele chama essa rotina. O gerente de E/S garante que o nome seja exclusivo. Normalmente, essa característica é especificada por um driver de barramento PnP para gerar um nome para um PDO (objeto de dispositivo físico) para um dispositivo filho no mesmo barramento. |
| FILE_CHARACTERISTIC_PNP_DEVICE | Indica que o objeto do dispositivo faz parte de uma pilha de Plug and Play (PnP). Essa característica será necessária se um motorista de barramento (ou driver de filtro de ônibus) registrar suporte de WMI para um objeto de dispositivo que ainda não recebeu a solicitação de IRP_MN_START_DEVICE . FILE_CHARACTERISTIC_PNP_DEVICE também será necessário se um driver de função ou filtro se registrar para WMI antes de anexar à pilha de dispositivos. |
| FILE_CHARACTERISTIC_TS_DEVICE | Indica que o objeto do dispositivo faz parte de uma pilha de dispositivos dos Serviços de Terminal. Os drivers não devem definir essa característica. |
| FILE_CHARACTERISTIC_WEBDAV_DEVICE | Indica que um sistema de arquivos WebDAV (Criação Distribuída e Controle de Versão) baseado na Web está montado no dispositivo. Os drivers não devem definir essa característica. |
| FILE_DEVICE_IS_MOUNTED | Indica que um sistema de arquivos está montado no dispositivo. Os drivers não devem definir essa característica. |
| FILE_DEVICE_SECURE_OPEN | Direciona o gerenciador de E/S para aplicar o descritor de segurança do objeto de dispositivo a aberturas relativas e o nome do arquivo à direita é aberto para o dispositivo. Para obter mais informações, consulte o tópico Controlando o acesso ao namespace do dispositivo . |
| FILE_FLOPPY_DISKETTE | Indica que o dispositivo é um dispositivo de disquete. |
| FILE_READ_ONLY_DEVICE | Indica que o dispositivo não pode ser gravado. |
| FILE_REMOTE_DEVICE | Indica que o dispositivo é remoto. |
| FILE_REMOVABLE_MEDIA | Indica que o dispositivo de armazenamento dá suporte a mídia removível. Observe que essa característica indica uma mídia removível, não um dispositivo removível. Por exemplo, os drivers para dispositivos de unidade JAZ devem especificar essa característica, mas os drivers para discos flash PCMCIA não devem. |
| FILE_VIRTUAL_VOLUME | Indica que o volume é virtual. Os drivers não devem definir essa característica. |
| FILE_WRITE_ONCE_MEDIA | Indica que o dispositivo dá suporte à mídia write-once. Os drivers não definem esse membro diretamente. Para obter mais informações sobre como definir características do dispositivo, consulte o tópico Especificando características do dispositivo . |
| FILE_CHARACTERISTIC_CSV | Indica que o dispositivo é um CSV (Volume Compartilhado Clusterizado). |
| FILE_DEVICE_ALLOW_APPCONTAINER_TRAVERSAL | O Gerenciador de E/S normalmente executa uma marcar de segurança completa para percorrer o acesso em cada arquivo aberto quando o cliente é um contêiner de aplicativo. A configuração desse sinalizador ignorará esse acesso de passagem imposta marcar se o token de cliente já tiver privilégios de passagem. |
| FILE_PORTABLE_DEVICE | Indica que a pilha subjacente considera o dispositivo portátil. Isso é usado pela pilha de armazenamento e significa que o dispositivo não está no contêiner do computador local e não está em um tipo de barramento fixo. |
Vpb
Um ponteiro para o VPB (bloco de parâmetros de volume) associado ao objeto do dispositivo. Para drivers do sistema de arquivos, a VPB pode fornecer uma conexão com qualquer objeto de dispositivo lógico sem nome que represente uma instância de um volume montado. Este é um membro opaco.
DeviceExtension
Um ponteiro para a extensão do dispositivo. A estrutura e o conteúdo da extensão do dispositivo são definidos pelo driver. O tamanho é determinado pelo driver, especificado na chamada do driver para IoCreateDevice ou IoCreateDeviceSecure. Para obter mais informações sobre extensões de dispositivo, consulte Extensões de dispositivo. Este é um membro somente leitura. No entanto, o objeto para o qual o membro aponta pode ser modificado pelo driver.
DeviceType
Definido por IoCreateDevice e IoCreateDeviceSecure usando o valor especificado para o parâmetro DeviceType dessa rotina. Para obter mais informações, consulte o tópico Especificando tipos de dispositivo .
StackSize
Especifica o número mínimo de locais de pilha em IRPs a serem enviados para esse driver. IoCreateDevice e IoCreateDeviceSecure definem esse membro como 1 em objetos de dispositivo recém-criados; Os drivers de nível mais baixo podem, portanto, ignorar esse membro. O gerenciador de E/S define automaticamente o membro StackSize em um objeto de dispositivo de driver de nível superior como o valor apropriado se o driver chamar IoAttachDevice ou IoAttachDeviceToDeviceStack. Somente um driver de nível superior que se encadeia por outro driver com IoGetDeviceObjectPointer deve definir explicitamente o valor de StackSize em seus próprios objetos de dispositivo como 1 + o valor StackSize do objeto de dispositivo do driver mais baixo.
Queue
Usado internamente pelo gerenciador de E/S para enfileirar o objeto do dispositivo quando ele é necessário. Este é um membro opaco.
Queue.ListEntry
Uma estrutura LIST_ENTRY que contém ponteiros para frente e para trás para uma lista duplamente vinculada.
Queue.Wcb
Informações de contexto do dispositivo usadas pelo gerenciador de E/S.
AlignmentRequirement
Especifica o requisito de alinhamento de endereço do dispositivo para transferências de dados. O valor deve ser um dos valores FILE_XXX_ALIGNMENT definidos em Wdm.h. Para obter mais informações, consulte os tópicos Inicializando um objeto de dispositivo, GetDmaAlignment e ZwQueryInformationFile .
DeviceQueue
O objeto de fila do dispositivo para o objeto do dispositivo. O objeto de fila do dispositivo contém todos os IRPs que estão aguardando para serem processados pelo driver associado ao objeto do dispositivo. Para obter mais informações, consulte o tópico Filas IRP gerenciadas pelo driver . Este é um membro opaco.
Dpc
O objeto DPC (chamada de procedimento adiado) para o objeto do dispositivo. Para obter mais informações, consulte o tópico Introdução aos objetos DPC . Este é um membro opaco.
ActiveThreadCount
Reservado para uso futuro. Este é um membro opaco.
SecurityDescriptor
Especifica um descritor de segurança (SECURITY_DESCRIPTOR) para o objeto de dispositivo quando o objeto do dispositivo é criado. Se esse membro for NULL, o objeto de dispositivo receberá as configurações de segurança padrão. Esse é um membro somente leitura, embora o membro possa ser modificado por meio da função ZwSetSecurityObject .
DeviceLock
Um objeto de evento de sincronização alocado pelo gerenciador de E/S. O gerente de E/S obtém seu objeto de evento antes de expedir uma solicitação de montagem ou verificação de montagem para um driver do sistema de arquivos. Este é um membro opaco.
SectorSize
Se o objeto do dispositivo não representar um volume, esse membro será definido como zero. Se o objeto de dispositivo representar um volume, esse membro especificará o tamanho do setor do volume, em bytes. O gerenciador de E/S usa esse membro para garantir que todas as operações de leitura, operações de gravação e definir operações de posição de arquivo emitidas sejam alinhadas corretamente quando o buffer intermediário estiver desabilitado. Um valor padrão de bytes do sistema por setor é usado quando o objeto de dispositivo é criado, no entanto, drivers do sistema de arquivos; e, mais raramente, drivers herdados e de minifiltro podem atualizar esse valor com base na geometria do hardware de volume subjacente quando ocorre uma montagem. Outros drivers não devem modificar esse membro.
Spare1
Reservado para uso do sistema. Este é um membro opaco.
DeviceObjectExtension
Um ponteiro para uma extensão de objeto de dispositivo que é usada pelo gerenciador de E/S e pelo gerenciador de PnP para armazenar informações sobre o estado do dispositivo. Este é um membro opaco.
Reserved
Reservado para uso do sistema. Este é um membro opaco.
Comentários
O sistema operacional representa dispositivos por objetos de dispositivo. Para obter mais informações, consulte o tópico Objetos de Dispositivo e Pilhas de Dispositivos .
Os drivers criam objetos de dispositivo usando as rotinas IoCreateDevice e IoCreateDeviceSecure . Para obter mais informações sobre como criar objetos de dispositivo, consulte Criando um objeto de dispositivo.
Um objeto de dispositivo é parcialmente opaco. Os drivers não definem membros do objeto do dispositivo diretamente, a menos que documentados de outra forma. Para obter mais informações sobre os membros que os drivers podem modificar diretamente, consulte Inicializando um objeto de dispositivo. Para obter informações sobre outras propriedades de objeto de dispositivo, consulte Propriedades de objetos de dispositivo.
Membros opacos dentro de um objeto de dispositivo devem ser considerados inacessíveis. Drivers que têm dependências em locais de membro do objeto ou acesso a membros opacos podem não permanecer portáteis e interoperáveis com outros drivers ao longo do tempo.
O driver de porta de vídeo fornecido pelo sistema configura os campos dos objetos de dispositivo que ele cria em nome de drivers de miniporto de vídeo.
O driver de porta SCSI fornecido pelo sistema configura os campos dos objetos de dispositivo que ele cria em nome de drivers de miniporta SCSI.
A biblioteca NDIS fornecida pelo sistema configura os campos dos objetos de dispositivo que ela cria em nome de drivers de miniporta NDIS.
Requisitos
| Requisito | Valor |
|---|---|
| Cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h) |