Objetos de arquivo do Framework

Quando um aplicativo ou um driver tenta acessar um dispositivo, normalmente criando ou abrindo um arquivo, o sistema operacional envia uma solicitação de criação de arquivo para a pilha de drivers. Quando a aplicação ou o driver terminar de usar o dispositivo, o sistema envia solicitações de limpeza de arquivos e encerramento à pilha de drivers. Os tipos de solicitação dessas três solicitações são WdfRequestTypeCreate, WdfRequestTypeCleanup e WdfRequestTypeClose, respectivamente.

Normalmente, a menos que o driver tenha chamado WdfDeviceInitSetExclusive, o driver deve executar operações específicas de arquivo ou outras operações específicas de acesso quando recebe solicitações de criação, limpeza e fechamento de arquivos, porque vários arquivos podem ser abertos simultaneamente ou vários aplicativos podem acessar o dispositivo simultaneamente. O driver deve, portanto, manter o controle das solicitações de E/S associadas a cada arquivo ou aplicativo.

A estrutura define objetos de arquivo de estrutura, que representam os meios de um aplicativo ou driver para acessar um dispositivo, como um arquivo, diretório, volume, slot de email, pipe nomeado ou o dispositivo inteiro. Um nome de arquivo pode ser associado a um objeto de arquivo, mas o significado de um nome de arquivo é específico do driver. Para obter mais informações sobre nomes de arquivo, consulte Controlando o acesso ao namespace do dispositivo.

Se o driver precisa manipular operações de ficheiro, ele deve chamar WdfDeviceInitSetFileObjectConfig de dentro da sua função de retorno de chamada EvtDriverDeviceAdd. O método WdfDeviceInitSetFileObjectConfig recebe uma estrutura WDF_FILEOBJECT_CONFIG como entrada. O driver usa esta estrutura para registrar as suas funções de retorno de chamada EvtDeviceFileCreate, EvtFileCleanup e EvtFileClose e, opcionalmente, para indicar se o framework deve criar um objeto de arquivo de framework cada vez que o driver recebe uma solicitação de criação de arquivo.

A maioria dos drivers que manipulam operações de arquivo armazenam informações específicas do arquivo no espaço de contexto do objeto de arquivo de estrutura. Se o driver lida com operações de arquivo, mas não precisa armazenar informações no espaço de contexto de um objeto de arquivo, a estrutura não precisa criar objetos de arquivo de estrutura para o driver.

Criando ou abrindo um arquivo

Quando a estrutura recebe uma solicitação de criação de arquivo para seu driver de função, ele:

1. Cria um objeto de arquivo de estrutura que representa o arquivo, a menos que o driver tenha indicado anteriormente que não precisa usar objetos de arquivo de estrutura.

2. Chama a função de callback EvtDeviceFileCreate do seu driver, se o driver tiver registrado a função de callback.

A função de retorno de chamada EvtDeviceFileCreate normalmente obtém informações sobre o arquivo, como seu nome e sinalizadores de objeto de arquivo. O driver normalmente armazena essas informações no espaço de contexto do objeto de arquivo de estrutura.

O driver pode, em vez de fornecer uma função de retorno de chamada EvtDeviceFileCreate, chamar WdfDeviceConfigureRequestDispatching para definir uma fila de E/S que receba todas as solicitações de criação de arquivo (solicitação do tipo WdfRequestTypeCreate). O driver receberá subsequentemente solicitações de criação de arquivo no manipulador de solicitações EvtIoDefault da fila. (Uma fila de E/S não pode receber solicitações de criação de arquivo se o membro DefaultQueue da estrutura WDF_IO_QUEUE_CONFIG da fila estiver definido como TRUE.)

Se o seu driver não fornecer uma função de retorno de chamada EvtDeviceFileCreate e não configurar uma fila de E/S para lidar com solicitações de E/S do tipo WdfRequestTypeCreate, a estrutura:

• Conclui todas as solicitações de criação de arquivo para o driver com um valor de status de STATUS_SUCCESS, caso o seu driver seja um driver de função.

• Encaminha todas as solicitações de criação de arquivos para o próximo driver inferior, se o driver for um driver de filtro.

(Para ver como você pode alterar esse comportamento, consulte o membro AutoForwardCleanupClose da estrutura WDF_FILEOBJECT_CONFIG .)

Observação Se o driver de função não fornecer nenhuma interface de dispositivo que os aplicativos possam usar para acessar os dispositivos do driver, o driver deverá fornecer uma função de retorno de chamada EvtDeviceFileCreate que conclua todas as solicitações de criação de arquivos com um valor de status para o qual NT_SUCCESS(status) é igual a FALSE. Caso contrário, um aplicativo mal-intencionado pode tentar acessar um dispositivo usando o nome do objeto de dispositivo físico (DOP) do dispositivo. (Todas as DOP têm nomes.)

Se um driver encaminhar uma solicitação de criação para um destino de E/S, o driver não deverá posteriormente concluir a solicitação com um valor de status de falha, a menos que o driver receba um valor de status de falha do destino de E/S. Caso contrário, os drivers inferiores não serão notificados de que a solicitação de criação falhou e podem tentar operar como se o arquivo estivesse aberto.

Se um driver encaminhar um pedido de criação para um destino de E/S, o driver não pode definir o sinalizador WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET se a estrutura tiver criado um objeto de arquivo do framework para o pedido de criação. Portanto, o driver não pode definir o sinalizador de WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET para uma solicitação de criação, a menos que também defina o sinalizador WdfFileObjectNotRequired. Isso ocorre porque o driver não será capaz de limpar o WDFFILEOBJECT no caso de um driver mais baixo na pilha negar a solicitação de criação. Em vez disso, o driver pode usar quaisquer outras opções de envio, por exemplo, enviar de forma assíncrona com uma rotina de conclusão ou enviar de forma síncrona. Em ambos os casos, o driver deve chamar WdfRequestComplete quando recuperar o controle.

Nota que, se um driver concluir uma solicitação de criação com um status de erro, a framework excluirá o objeto de arquivo da framework, mas não chamará as funções de retorno de chamada EvtFileCleanup ou EvtFileClose do driver. Portanto, se o driver aloca memória específica de objeto extra fora do espaço de contexto do objeto de arquivo, ele deve fornecer uma função de retorno de chamada EvtCleanupCallback ou EvtDestroyCallback que exclui a memória alocada.

Para o Windows Vista e versões posteriores, as solicitações de criação de arquivos podem ser canceladas. As versões anteriores do sistema operativo Windows não suportam o cancelamento de pedidos de criação de ficheiros.

O sistema sempre cria um objeto de arquivo WDM (Windows Driver Model) para cada solicitação de criação que vem de um aplicativo de usuário. Se um driver enviar uma solicitação de criação, ele pode não criar um objeto de arquivo WDM para a solicitação. Normalmente, a estrutura não cria um objeto de arquivo de estrutura se um objeto de arquivo WDM não estiver presente. No entanto, se o driver tiver chamado WdfDeviceInitSetExclusive e se o driver tiver definido WdfFileObjectWdfCannotUseFsContexts no membro FileObjectClass da estrutura WDF_FILEOBJECT_CONFIG, o framework criará um objeto de arquivo de framework mesmo se um objeto de arquivo WDM não existir.

Obtendo informações de arquivo

A função de retorno de chamada EvtDeviceFileCreate do driver pode chamar um ou vários dos seguintes métodos de objeto para obter informações sobre o acesso de um aplicativo ou de um driver a um dispositivo:

WdfFileObjectGetFileName
Retorna o nome de arquivo contido em um objeto de arquivo de estrutura.

WdfFileObjectGetFlags
Retorna os sinalizadores contidos em um objeto de arquivo de estrutura.

WdfFileObjectWdmGetFileObject
Retorna o objeto de arquivo WDM associado a um objeto de arquivo de estrutura.

WdfRequestGetParameters
Recupera os parâmetros associados a um objeto de solicitação de estrutura. Se o tipo de solicitação for WdfRequestTypeCreate, o membro Parameters.Create da estrutura WDF_REQUEST_PARAMETERS conterá informações sobre a solicitação de criação de arquivo.

Normalmente, o driver armazena informações de arquivo no espaço de contexto do objeto de arquivo de estrutura. Quando o driver obtém uma solicitação de E/S de uma das suas filas de E/S, o driver pode chamar WdfRequestGetFileObject para obter um identificador para o objeto de arquivo do framework que está associado à solicitação. O driver pode então recuperar as informações de arquivo que ele armazenou no espaço de contexto do objeto de arquivo de estrutura.

Seu driver pode pesquisar uma fila de E/S para solicitações associadas a um arquivo específico chamando WdfIoQueueRetrieveRequestByFileObject.

Se o driver tiver um ponteiro para uma estrutura de DEVICE_OBJECT WDM, o driver poderá chamar WdfDeviceGetFileObject para obter um identificador para o objeto de arquivo de estrutura associado ao objeto de dispositivo WDM.

Fechar um ficheiro

Quando um aplicativo ou outro driver fecha um arquivo, a estrutura recebe uma solicitação de limpeza e uma solicitação de fechamento para seu driver. O quadro:

1. Chama as funções de retorno de chamada EvtFileCleanup e EvtFileClose do seu driver, se o driver tiver registrado essas funções de retorno de chamada.

2. Exclui o objeto de arquivo de estrutura que representa o arquivo.

As funções de retorno de chamada EvtFileCleanup e EvtFileClose do driver recebem um identificador para o objeto de arquivo de estrutura. O driver pode chamar WdfFileObjectGetDevice para determinar qual objeto de dispositivo de estrutura está associado ao objeto de arquivo de estrutura.