Пространство контекста объекта Framework

#B0 Пространство контекста объекта #C1 — это дополнительное, не загружаемое в память пространство памяти, которое драйвер может выделить и назначить объекту. Каждый драйвер на основе платформы может создавать одно или несколько контекстных пространств для каждого объекта платформы, который драйвер получает или создает.

Драйверы на основе платформы должны хранить все данные, относящиеся к объекту, либо по значению, либо по указателю в пространстве контекста объекта, к которому принадлежат данные.

Например, драйвер для USB-устройств может создать пространство контекста для объектов устройств платформы. В пространстве контекста драйвер может хранить такие сведения, относящиеся к устройству, как #B0 #A1 USB_DEVICE_DESCRIPTOR #A2 #C3 устройства и структуры #B4 #A5 USB_CONFIGURATION_DESCRIPTOR #A6 #C7, а также дескриптор коллекции объектов #B8 #C9, представляющей каналы ввода-вывода интерфейса устройства.

Платформа не передает объекты платформы от одного драйвера к другому, поэтому нельзя использовать пространство контекста объекта для передачи данных между двумя драйверами.

Чтобы определить пространство контекста объекта, необходимо создать одну или несколько структур. Каждая структура представляет отдельное пространство контекста. Драйвер будет использовать каждый элемент структуры для хранения фрагмента информации, относящегося к объекту. Кроме того, драйвер должен попросить фреймворк создать метод доступа для каждой структуры. Этот аксессор принимает дескриптор объекта как входной параметр и возвращает адрес контекстного пространства объекта.

Всякий раз, когда драйвер вызывает метод создания объекта, например WdfDeviceCreate, метод при необходимости выделяет пространство контекста. Все методы создания объектов принимают необязательную структуру WDF_OBJECT_ATTRIBUTES в качестве входных данных. Эта структура описывает пространство контекста, которое требуется выделить платформе для объекта.

Чтобы добавить дополнительное пространство контекста к объекту после того, как драйвер вызвал метод его создания, драйвер может вызвать метод #B0 #A1 WdfObjectAllocateContext #A2 #C3, который, подобно методам создания объекта, принимает структуру #B4 #A5 WDF_OBJECT_ATTRIBUTES #A6 #C7 в качестве входного параметра.

Когда платформа выделяет пространство контекста для объекта, она также инициализирует это пространство нулевым значением.

Когда платформа или драйвер удаляет объект платформы, платформа удаляет все пространство контекста объекта.

Если ваш драйвер использует пространство контекста для хранения указателей на буферы, которые драйвер выделяет при создании объекта, то он должен предоставить функцию EvtCleanupCallback, которая освобождает эти буферы при удалении объекта.

Чтобы определить структуру пространства объекта и метод доступа для создаваемых вами объектов, драйвер должен выполнить следующие действия.

1. Определите структуру, описывающую данные, которые требуется хранить. Например, если вы хотите создать данные контекста для объектов устройства драйвера, драйвер может определить структуру, называемую MY_DEVICE_CONTEXT.

2. Используйте макрос WDF_DECLARE_CONTEXT_TYPE или макрос WDF_DECLARE_CONTEXT_TYPE_WITH_NAME. Оба этих макроса выполняют следующие действия:

   • Создайте и инициализируйте структуру WDF_OBJECT_CONTEXT_TYPE_INFO.
   • Определите метод доступа, который драйвер позже будет использовать для доступа к пространству контекста объекта. Возвращаемое значение метода доступа — это указатель на пространство контекста объекта.

   Макрос WDF_DECLARE_CONTEXT_TYPE создает имя метода доступа на основе имени вашей структуры. Например, если имя структуры контекста — MY_DEVICE_CONTEXT, макрос создает метод доступа, который называется WdfObjectGet_MY_DEVICE_CONTEXT.

   Макрос WDF_DECLARE_CONTEXT_TYPE_WITH_NAME позволяет указать имя метода доступа. Например, можно указать GetMyDeviceContext в качестве имени метода доступа к контексту устройств.

3. Вызовите WDF_OBJECT_ATTRIBUTES_INIT, чтобы инициализировать структуру WDF_OBJECT_ATTRIBUTES объекта.

4. Используйте макрос WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE, чтобы установить элемент ContextTypeInfo структуры WDF_OBJECT_ATTRIBUTES на адрес структуры WDF_OBJECT_CONTEXT_TYPE_INFO.

5. Вызовите метод создания объекта, например, WdfDeviceCreate.

После того как ваш драйвер создал объект, он может в любое время вызвать WdfObjectAllocateContext, чтобы добавить дополнительное пространство контекста объекту.

Так как шаги 1 и 2 определяют глобальные структуры данных и создают вызываемую драйвером подпрограмму, драйвер должен выполнить эти действия в области драйвера, которая объявляет глобальные данные, как правило, файл заголовка. Эти действия не должны выполняться из подпрограмм драйвера.

Драйвер должен выполнить шаги 3, 4 и 5 внутри подпрограммы драйвера, создающей объект, например, обратном вызове EvtDriverDeviceAdd, который вызывает WdfDeviceCreate.

Платформа может создавать два типа объектов — объекты запроса платформы и объекты файлов платформы от имени драйвера. Драйвер может зарегистрировать пространство контекста для этих объектов, вызвав WdfDeviceInitSetRequestAttributes и WdfDeviceInitSetFileObjectConfig соответственно. Ваш драйвер также может вызвать WdfObjectAllocateContext, чтобы выделить пространство контекста для этих объектов.

После создания объекта драйвер может получить указатель на пространство контекста объекта с помощью любого из следующих методов:

• Вызовите метод доступа к контексту, который вы создали на втором шаге в предыдущей процедуре, с помощью макроса WDF_DECLARE_CONTEXT_TYPE или WDF_DECLARE_CONTEXT_TYPE_WITH_NAME.

• Вызовите WdfObjectGetTypedContext, указав имя структуры контекста, определяемой драйвером.

Если драйвер имеет указатель на пространство контекста, он может найти объект, к которому относится пространство контекста, вызвав WdfObjectContextGetObject.