Espaço de contexto do objeto Framework

O espaço de contexto do objeto é um espaço de memória extra, não pageable que um driver pode alocar e atribuir a um objeto. Cada driver baseado em estrutura pode criar um ou mais espaços de contexto específicos ao objeto para cada objeto de estrutura que o driver recebe ou cria.

Os drivers baseados em estrutura devem armazenar todos os dados específicos do objeto, seja por valor ou por ponteiro, dentro do espaço de contexto do objeto ao qual os dados pertencem.

Por exemplo, um driver para dispositivos USB pode criar espaço de contexto para seus objetos de dispositivo de estrutura. No espaço de contexto, o driver pode armazenar informações específicas do dispositivo como as estruturas USB_DEVICE_DESCRIPTOR e USB_CONFIGURATION_DESCRIPTOR do dispositivo, além de um identificador para um objeto de coleção que representa os pipes de uma interface do dispositivo.

A estrutura não passa objetos de estrutura de um driver para outro, portanto, você não pode usar o espaço de contexto de um objeto para passar dados entre dois drivers.

Para definir o espaço de contexto de um objeto, você deve criar uma ou mais estruturas. Cada estrutura representa um espaço de contexto separado. Seu driver usará cada membro da estrutura para armazenar uma parte das informações específicas do objeto. Além disso, o driver deve pedir à estrutura para gerar um método de acessador para cada estrutura. Esse método acessador aceita um identificador de objeto como entrada e retorna o endereço do espaço de contexto do objeto.

Sempre que o driver chama um método de criação de objeto, como WdfDeviceCreate, o método aloca opcionalmente espaço de contexto. Todos os métodos de criação de objeto aceitam uma estrutura de WDF_OBJECT_ATTRIBUTES opcional como entrada. Essa estrutura descreve o espaço de contexto que você deseja que a estrutura aloque para o objeto .

Para adicionar espaço de contexto adicional a um objeto depois que o driver tiver chamado o método de criação do objeto, o driver pode chamar o método WdfObjectAllocateContext , que, como os métodos de criação de objeto, aceita uma estrutura WDF_OBJECT_ATTRIBUTES como entrada.

Quando a estrutura aloca espaço de contexto para um objeto, ela também inicializa o espaço de contexto.

Quando a estrutura ou um driver exclui um objeto de estrutura, a estrutura exclui todo o espaço de contexto do objeto.

Se o driver usar espaço de contexto para armazenar ponteiros para buffers alocados pelo driver ao criar um objeto, o driver deverá fornecer uma função EvtCleanupCallback que desaloca os buffers quando o objeto é excluído.

Para definir a estrutura de espaço de contexto e o método do acessador de um objeto para os objetos que o driver cria, o driver deve usar as seguintes etapas:

1. Defina uma estrutura que descreva os dados que você deseja armazenar. Por exemplo, se você quiser criar dados de contexto para os objetos de dispositivo do driver, o driver poderá definir uma estrutura chamada MY_DEVICE_CONTEXT.

2. Use a macro WDF_DECLARE_CONTEXT_TYPE ou a macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME . Ambas as macros fazem o seguinte:

   • Criar e inicializar uma estrutura de WDF_OBJECT_CONTEXT_TYPE_INFO .
   • Defina um método de acessador que seu driver usará posteriormente para acessar o espaço de contexto de um objeto. O valor retornado do método acessador é um ponteiro para o espaço de contexto do objeto.

   A macro WDF_DECLARE_CONTEXT_TYPE cria o nome do método acessador com base no nome da estrutura. Por exemplo, se o nome da estrutura de contexto for MY_DEVICE_CONTEXT, a macro criará um método acessador chamado WdfObjectGet_MY_DEVICE_CONTEXT.

   A macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME permite especificar o nome do método acessador. Por exemplo, você pode especificar GetMyDeviceContext como o nome do método acessador de contexto para objetos de dispositivo.

3. Chame WDF_OBJECT_ATTRIBUTES_INIT para inicializar a estrutura de WDF_OBJECT_ATTRIBUTES do objeto.

4. Use a macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE para definir o membro ContextTypeInfo da estrutura WDF_OBJECT_ATTRIBUTES para o endereço da estrutura WDF_OBJECT_CONTEXT_TYPE_INFO.

5. Chame um método de criação de objeto, como WdfDeviceCreate.

Depois que o driver tiver criado um objeto, o driver poderá chamar WdfObjectAllocateContext a qualquer momento para adicionar espaço de contexto adicional ao objeto.

Como as etapas 1 e 2 definem estruturas de dados globais e criam uma rotina que pode ser chamada pelo driver, o driver deve concluir essas etapas em uma área do driver que declara dados globais— normalmente um arquivo de cabeçalho. Essas etapas não devem ser concluídas de dentro das rotinas do driver.

Seu driver deve concluir as etapas 3, 4 e 5 de dentro de uma rotina de driver que cria um objeto, como uma função de retorno de chamada EvtDriverDeviceAdd que chama WdfDeviceCreate.

A estrutura pode criar dois tipos de objetos – objetos de solicitação de estrutura e objetos de arquivo de estrutura – em nome do driver. Seu driver pode registrar espaço de contexto para esses objetos chamando WdfDeviceInitSetRequestAttributes e WdfDeviceInitSetFileObjectConfig, respectivamente. Seu driver também pode chamar WdfObjectAllocateContext para alocar espaço de contexto para esses objetos.

Depois que um objeto for criado, o driver poderá obter um ponteiro para o espaço de contexto do objeto usando uma das seguintes técnicas:

• Chame o método de acessador de contexto que você criou na etapa 2 no procedimento anterior usando o WDF_DECLARE_CONTEXT_TYPE ou a macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME .

• Chame WdfObjectGetTypedContext, fornecendo o nome da estrutura de contexto definida pelo driver.

Se o driver tiver um ponteiro de espaço de contexto, ele poderá encontrar o objeto ao qual o espaço de contexto pertence chamando WdfObjectContextGetObject.