Espaço de contexto do objeto do Framework

O espaço de contexto de objeto é um espaço de memória extra, não paginável, 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 do 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, 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 os objetos de dispositivos da sua framework. 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, além de um identificador para um objeto de coleção que representa as pipelines 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 seu driver deve pedir ao "framework" para gerar um método de acesso para cada estrutura. Esse método de 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 opcionalmente aloca espaço de contexto. Todos os métodos de criação de objetos aceitam uma estrutura 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 chamou o método de criação do objeto, o driver pode chamar o WdfObjectAllocateContext método - 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 zero 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 usa espaço de contexto para armazenar ponteiros para buffers que aloca quando cria um objeto, o driver deve fornecer uma função EvtCleanupCallback que desaloca os buffers quando o objeto é eliminado.

Para definir a estrutura de espaço de contexto de um objeto e o método de acesso 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 pode definir uma estrutura chamada MY_DEVICE_CONTEXT.

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

   • Crie e inicialize uma estrutura WDF_OBJECT_CONTEXT_TYPE_INFO.
   • Defina um método de acesso que seu driver usará posteriormente para acessar o espaço de contexto de um objeto. O valor de retorno do método accessor é um ponteiro para o espaço de contexto do objeto.

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

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

3. Chame WDF_OBJECT_ATTRIBUTES_INIT para inicializar a estrutura 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 chamável por driver, o driver deve concluir essas etapas em uma área do driver que declara dados globais - normalmente um arquivo de cabeçalho. Estes passos não devem ser concluídos a partir das rotinas do seu motorista.

O seu driver deve concluir as etapas 3, 4 e 5 dentro de uma rotina de driver que cria um objeto, como uma função callback 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 seu 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 foi criado, o driver pode 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 se criou na etapa 2 do procedimento anterior usando a macro WDF_DECLARE_CONTEXT_TYPE ou a macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME.

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

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