Objetos de arquivo de estrutura

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 driver. Quando o aplicativo ou driver terminar de usar o dispositivo, o sistema enviará a limpeza de arquivos e fechará as solicitações para a pilha de driver. 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 receber solicitações de criação, limpeza e fechamento de arquivos, pois vários arquivos podem ser abertos simultaneamente ou vários aplicativos podem acessar o dispositivo simultaneamente. Portanto, o driver deve acompanhar as 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 todo o dispositivo. 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 precisar manipular operações de arquivo, ele deverá chamar WdfDeviceInitSetFileObjectConfig de dentro de sua função de retorno de chamada EvtDriverDeviceAdd . O método WdfDeviceInitSetFileObjectConfig recebe uma estrutura WDF_FILEOBJECT_CONFIG como entrada. O driver usa essa estrutura para registrar suas funções de retorno de chamada EvtDeviceFileCreate, EvtFileCleanup e EvtFileClose e, opcionalmente, para indicar se a estrutura deve criar um objeto de arquivo de estrutura sempre que o driver receber uma solicitação de criação de arquivo.

A maioria dos drivers que lidam com operações de arquivo armazena informações específicas do arquivo no espaço de contexto do objeto de arquivo de estrutura. Se o driver manipular operações de arquivo, mas não precisar armazenar informações no espaço de contexto de um objeto de arquivo, a estrutura não precisará 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 o driver de função, ela:

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. Chamará a função de retorno de chamada EvtDeviceFileCreate do driver se o driver tiver registrado a função de retorno de chamada.

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.

Em vez de fornecer uma função de retorno de chamada EvtDeviceFileCreate , o driver pode chamar WdfDeviceConfigureRequestDispatching para definir uma fila de E/S para receber todas as solicitações de criação de arquivo (tipo de solicitação WdfRequestTypeCreate ). O driver receberá posteriormente solicitações de criação de arquivo no manipulador de solicitações EvtIoDefault da fila. (Uma fila de E/S não poderá 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 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 status de STATUS_SUCCESS, se o driver for um driver de função.

• Encaminha todas as solicitações de criação de arquivo para o driver inferior seguinte, 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 .)

Nota 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 arquivo 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 PDO (objeto de dispositivo físico) do dispositivo. (Todos os PDOs têm nomes.)

Se um driver encaminhar uma solicitação de criação para um destino de E/S, o driver não deverá concluir posteriormente a solicitação com uma falha status valor, a menos que o driver receba uma falha status valor 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 poderão tentar operar como se o arquivo estivesse aberto.

Se um driver encaminhar uma solicitação de criação para um destino de E/S, o driver não poderá definir o sinalizador WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET se a estrutura tiver criado um objeto de arquivo de estrutura para a solicitação de criação. Portanto, o driver não pode definir o sinalizador WDF_REQUEST_SEND_OPTION_SEND_AND_FORGET para uma solicitação de criação, a menos que ele também defina o sinalizador WdfFileObjectNotRequired, pois o driver não poderá limpo o WDFFILEOBJECT caso um driver inferior na pilha falhe na solicitação de criação. Em vez disso, o driver pode usar qualquer outra opção 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.

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

Para o Windows Vista e posteriores, as solicitações de criação de arquivo podem ser canceladas. Versões anteriores do sistema operacional Windows não dão suporte ao cancelamento de solicitações de criação de arquivo.

O sistema sempre cria um objeto de arquivo WDM (Modelo de Driver do Windows) para cada solicitação de criação proveniente de um aplicativo de usuário. Se um driver enviar uma solicitação de criação, ele poderá não criar um objeto de arquivo WDM para a solicitação. Normalmente, a estrutura não criará 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 , a estrutura criará um objeto de arquivo de estrutura mesmo que um objeto de arquivo WDM não exista.

Obtendo informações de arquivo

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

WdfFileObjectGetFileName
Retorna o nome do 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 se suas filas de E/S, o driver pode chamar WdfRequestGetFileObject para obter um identificador para o objeto de arquivo de estrutura associado à solicitação. Em seguida, o driver pode recuperar as informações de arquivo armazenadas no espaço de contexto do objeto de arquivo de estrutura.

O driver pode pesquisar solicitações associadas a um arquivo específico em uma fila de E/S 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.

Fechando um arquivo

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

1. Chama as funções de retorno de chamada EvtFileCleanup e EvtFileClose do 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.