Criando e Usando Objetos de Arquivo Driver-Created

Advertência

UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser escritos usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar UMDF 2.

Os exemplos de UMDF 1 arquivados podem ser encontrados na Windows 11, versão 22H2 - Atualização de Amostras de Driver de maio de 2022.

Para obter mais informações, consulte Introdução ao UMDF.

Se o driver precisar criar e enviar uma solicitação de E/S independente da aplicação para o próximo driver na pilha (o alvo de E/S predefinido), o driver deve criar e fechar os seus próprios objetos de ficheiro.

Criando um objeto de arquivo

Seu driver deve chamar o método IWDFDevice::CreateWdfFile para criar um objeto de arquivo para uso do driver. Quando o driver chama IWDFDevice::CreateWdfFile, a estrutura envia uma solicitação de criação para o próximo driver na pilha. O próximo driver na pilha pode estar no modo kernel ou no modo de usuário.

Esse processamento de solicitação de arquivo de criação é diferente no WDM (Windows Driver Model). No WDM, uma chamada para a função ZwCreateFile faz com que um IRP de criação vá para o topo da pilha de modo kernel. A figura a seguir mostra o processamento de solicitação de criação de arquivo no UMDF em comparação com o WDM.

Ao chamar IWDFDevice::CreateWdfFile, o driver pode criar um objeto de arquivo e, em seguida, enviar solicitações de E/S durante o início do dispositivo, antes que toda a pilha tenha começado.

O próximo driver na pilha deve determinar se ele pode lidar com a solicitação de arquivo de criação ou se ele deve encaminhar a solicitação mais abaixo na pilha.

Depois de chamar IWDFDevice::CreateWdfFile, um driver não pode cancelar a operação de criação.

Usando o objeto File

Para enviar uma solicitação de leitura assíncrona para o próximo driver empilhado abaixo dele, seu driver pode usar o seguinte padrão.

1. Chame IWDFDevice::CreateWdfFile para criar o objeto de arquivo.
2. Chame IWDFDevice::GetDefaultIoTarget para recuperar a interface que representa o driver de nível inferior.
3. Chame IWDFDevice::CreateRequest para criar um objeto IWDFIoRequest não formatado.
4. Chame IWDFIoRequest::SetCompletionCallback para registar uma interface IRequestCallbackRequestCompletion para o método OnCompletion que o framework chama quando uma solicitação de E/S é concluída.
5. Chame IWDFIoTarget::FormatRequestForRead, fornecendo um ponteiro para a interface IWDFDriverCreatedFile no parâmetro pFile.
6. Chame IWDFIoRequest::Send para enviar a solicitação.

Fechando o objeto de arquivo

O driver que chamou IWDFDevice::CreateWdfFile deve posteriormente chamar IWDFDriverCreatedFile::Close.

Normalmente, o driver chama IWDFDriverCreatedFile::Close a partir do método de retorno de chamada IPnpCallbackHardware::OnReleaseHardware ou do IPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup.

Quando o driver chama IWDFDriverCreatedFile::Close, a estrutura chama o método IFileCallbackCleanup::OnCleanupFile do próximo driver. Nesse método, o próximo driver deve cancelar ou concluir todas as solicitações de E/S pendentes associadas ao objeto de arquivo. Em seguida, a estrutura cancela todas as solicitações de E/S criadas pelo driver chamado IWDFDevice::CreateWdfFile. O framework não cancela nenhuma solicitação de E/S que drivers de nível inferior na pilha possam ter associado ao objeto de arquivo. É da responsabilidade do condutor cancelar tais pedidos. O objeto de arquivo só fecha depois que todas as solicitações de E/S associadas a ele forem concluídas.

Em seguida, a estrutura chama o método IFileCallbackClose::OnCloseFile do próximo driver. Neste ponto, a estrutura garante que o próximo driver não receberá solicitações de E/S adicionais para esse objeto de arquivo.

Depois que a estrutura chama OnCloseFile, ela destrói a interface IWDFFile que representa o objeto de arquivo.

Se os objetos de arquivo criados pelo driver permanecerem após o retorno dos métodos de remoção de dispositivo do driver (por exemplo, IPnpCallbackHardware::OnReleaseHardware e IPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup), o framework gerará uma interrupção do driver. Para obter informações sobre como solucionar esse problema, consulte Determinando por que UMDF indica arquivos pendentes no momento da remoção do dispositivo.