Espacio de contexto de objeto de marco

  • Artículo

El espacio de contexto del objeto es adicional, no paginable, espacio de memoria que un controlador puede asignar y asignar a un objeto. Cada controlador basado en marcos puede crear uno o varios espacios de contexto específicos del objeto para cada objeto de marco que el controlador recibe o crea.

Los controladores basados en framework deben almacenar todos los datos específicos del objeto, ya sea por valor o por puntero, dentro del espacio de contexto del objeto al que pertenecen los datos.

Por ejemplo, un controlador para dispositivos USB podría crear espacio de contexto para sus objetos de dispositivo de marco. En el espacio de contexto, el controlador puede almacenar dicha información específica del dispositivo como las estructuras de USB_DEVICE_DESCRIPTOR y USB_CONFIGURATION_DESCRIPTOR del dispositivo, además de un identificador para un objeto de colección que representa las canalizaciones de una interfaz de dispositivo.

El marco de trabajo no pasa objetos de marco de un controlador a otro, por lo que no se puede usar el espacio de contexto de un objeto para pasar datos entre dos controladores.

Para definir el espacio de contexto de un objeto, debe crear una o varias estructuras. Cada estructura representa un espacio de contexto independiente. El controlador usará cada miembro de estructura para almacenar un fragmento de información específica del objeto. Además, el controlador debe pedir al marco que genere un método de descriptor de acceso para cada estructura. Este método de descriptor de acceso acepta un identificador de objeto como entrada y devuelve la dirección del espacio de contexto del objeto.

Cada vez que el controlador llama a un método de creación de objetos, como WdfDeviceCreate, el método asigna opcionalmente espacio de contexto. Todos los métodos de creación de objetos aceptan una estructura de WDF_OBJECT_ATTRIBUTES opcional como entrada. Esta estructura describe el espacio de contexto que desea que el marco asigne para el objeto .

Para agregar espacio de contexto adicional a un objeto después de que el controlador haya llamado al método de creación del objeto, el controlador puede llamar al método WdfObjectAllocateContext , que, al igual que los métodos de creación de objetos, acepta una estructura de WDF_OBJECT_ATTRIBUTES como entrada.

Cuando el marco asigna espacio de contexto para un objeto, también inicializa cero el espacio de contexto.

Cuando el marco o un controlador eliminan un objeto de marco, el marco elimina todo el espacio de contexto del objeto.

Si el controlador usa espacio de contexto para almacenar punteros a búferes que el controlador asigna cuando crea un objeto, el controlador debe proporcionar una función EvtCleanupCallback que desasigne los búferes cuando se elimine el objeto.

Para definir la estructura de espacio de contexto y el método de descriptor de acceso de un objeto para los objetos que crea el controlador, el controlador debe seguir estos pasos:

  1. Defina una estructura que describa los datos que desea almacenar. Por ejemplo, si desea crear datos de contexto para los objetos de dispositivo del controlador, el controlador podría definir una estructura denominada MY_DEVICE_CONTEXT.

  2. Use la macro WDF_DECLARE_CONTEXT_TYPE o la macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME . Ambas macros hacen lo siguiente:

    • Cree e inicialice una estructura de WDF_OBJECT_CONTEXT_TYPE_INFO .
    • Defina un método de descriptor de acceso que el controlador usará posteriormente para tener acceso al espacio de contexto de un objeto. El valor devuelto del método de descriptor de acceso es un puntero al espacio de contexto del objeto.

    La macro WDF_DECLARE_CONTEXT_TYPE crea el nombre del método de descriptor de acceso a partir del nombre de la estructura. Por ejemplo, si el nombre de la estructura de contexto es MY_DEVICE_CONTEXT, la macro crea un método de descriptor de acceso denominado WdfObjectGet_MY_DEVICE_CONTEXT.

    La macro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME permite especificar el nombre del método de descriptor de acceso. Por ejemplo, puede especificar GetMyDeviceContext como el nombre del método de descriptor de acceso de contexto para los objetos de dispositivo.

  3. Llame a WDF_OBJECT_ATTRIBUTES_INIT para inicializar la estructura de WDF_OBJECT_ATTRIBUTES del objeto.

  4. Use la macro WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE para establecer el miembro ContextTypeInfo de la estructura WDF_OBJECT_ATTRIBUTES en la dirección de la estructura WDF_OBJECT_CONTEXT_TYPE_INFO.

  5. Llame a un método de creación de objetos, como WdfDeviceCreate.

Después de que el controlador haya creado un objeto, el controlador puede llamar a WdfObjectAllocateContext en cualquier momento para agregar espacio de contexto adicional al objeto .

Dado que los pasos 1 y 2 definen estructuras de datos globales y crean una rutina invocable por el controlador, el controlador debe completar estos pasos en un área del controlador que declara datos globales, normalmente un archivo de encabezado. Estos pasos no deben completarse desde las rutinas del controlador.

El controlador debe completar los pasos 3, 4 y 5 desde dentro de una rutina de controlador que crea un objeto, como una función de devolución de llamada EvtDriverDeviceAdd que llama a WdfDeviceCreate.

El marco de trabajo puede crear dos tipos de objetos (objetos de solicitud de marco y objetos de archivo de marco) en nombre del controlador. El controlador puede registrar espacio de contexto para estos objetos llamando a WdfDeviceInitSetRequestAttributes y WdfDeviceInitSetFileObjectConfig, respectivamente. El controlador también puede llamar a WdfObjectAllocateContext para asignar espacio de contexto para estos objetos.

Una vez creado un objeto, el controlador puede obtener un puntero al espacio de contexto del objeto mediante cualquiera de las técnicas siguientes:

Si el controlador tiene un puntero de espacio de contexto, puede encontrar el objeto al que pertenece el espacio de contexto llamando a WdfObjectContextGetObject.