Criando e usando objetos de arquivo Driver-Created
Aviso
O UMDF 2 é a versão mais recente do UMDF e substitui o UMDF 1. Todos os novos drivers UMDF devem ser gravados 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 o UMDF 2.
Os exemplos de UMDF 1 arquivados podem ser encontrados no Windows 11, versão 22H2 – Atualização de exemplos de driver de maio de 2022.
Para obter mais informações, consulte Introdução com UMDF.
Se o driver precisar criar e enviar uma solicitação de E/S independente do aplicativo para o próximo driver na pilha (o destino de E/S padrão), o driver deverá criar e fechar seus próprios objetos de arquivo.
Criando um objeto file
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 criação de arquivo é diferente no WDM (Modelo de Driver do Windows). No WDM, uma chamada para a função ZwCreateFile faz com que um IRP de criação vá para a parte superior da pilha do modo kernel. A figura a seguir mostra o processamento de solicitação create-file no UMDF versus 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 seja iniciada.
O próximo driver na pilha deve determinar se ele pode lidar com a solicitação create-file ou se ele deve encaminhar a solicitação mais para baixo na pilha.
Depois de chamar IWDFDevice::CreateWdfFile, um driver não poderá 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 dela, o driver pode usar o padrão a seguir.
- Chame IWDFDevice::CreateWdfFile para criar o objeto de arquivo.
- Chame IWDFDevice::GetDefaultIoTarget para recuperar a interface que representa o driver de nível inferior.
- Chame IWDFDevice::CreateRequest para criar um objeto IWDFIoRequest não formatado.
- Chame IWDFIoRequest::SetCompletionCallback para registrar uma interface IRequestCallbackRequestCompletion para o método OnCompletion que a estrutura chama quando uma solicitação de E/S é concluída.
- Chame IWDFIoTarget::FormatRequestForRead, fornecendo um ponteiro para a interface IWDFDriverCreatedFile no parâmetro pFile .
- Chame IWDFIoRequest::Send para enviar a solicitação.
Fechando o objeto file
O driver que chamou IWDFDevice::CreateWdfFile deve chamar posteriormente IWDFDriverCreatedFile::Close.
Normalmente, seu driver chama IWDFDriverCreatedFile::Close de seu método de retorno de chamada IPnpCallbackHardware::OnReleaseHardware ou 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 que chamou IWDFDevice::CreateWdfFile. A estrutura não cancela nenhuma solicitação de E/S que drivers mais baixos na pilha possam ter associado ao objeto de arquivo. É responsabilidade do driver cancelar essas solicitações. O objeto de arquivo só é fechado 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 os métodos de remoção de dispositivo do driver (por exemplo , IPnpCallbackHardware::OnReleaseHardware e IPnpCallbackSelfManagedIo::OnSelfManagedIoCleanup) retornarem, a estrutura gerará uma parada de driver. Para obter informações sobre como solucionar esse problema, consulte Determinando por que o UMDF indica arquivos pendentes no tempo de remoção do dispositivo.