Kontextový prostor objektového rámce

kontextový prostor objektu je nadbytečné, nestránkové, paměťové místo, které může ovladač přidělit a přiřadit k objektu. Každý ovladač založený na rozhraní může vytvořit jeden nebo více kontextových prostorů specifických pro objekty architektury, které ovladač přijme nebo vytvoří.

Ovladače založené na frameworku by měly ukládat všechna data specifická pro objekty, a to buď podle hodnoty, nebo pomocí ukazatele, v rámci kontextu objektu, k němuž data patří.

Ovladač pro zařízení USB může například vytvořit kontextový prostor pro objekty zařízení architektury. V kontextovém prostoru může ovladač ukládat informace specifické pro zařízení, jako je struktura USB_DEVICE_DESCRIPTOR a struktura USB_CONFIGURATION_DESCRIPTOR, plus popisovač objektu kolekce , který představuje kanály rozhraní zařízení.

Architektura nepředává objekty architektury z jednoho ovladače do druhého, takže nelze použít kontextový prostor objektu pro předávání dat mezi dvěma ovladači.

Chcete-li definovat kontextový prostor objektu, musíte vytvořit jednu nebo více struktur. Každá struktura představuje samostatný kontextový prostor. Ovladač použije každý člen struktury k uložení části informací specifických pro objekt. Ovladač navíc musí požádat architekturu, aby pro každou strukturu vygenerovala metodu přístupového objektu. Tato přístupová metoda přijímá jako vstup popisovač objektu a vrací adresu kontextového prostoru objektu.

Kdykoli ovladač volá metodu vytvoření objektu, například WdfDeviceCreate, metoda volitelně přidělí kontextový prostor. Všechny metody vytváření objektů přijímají jako vstup volitelnou strukturu WDF_OBJECT_ATTRIBUTES. Tato struktura popisuje kontextový prostor, který má architektura přidělit objektu.

Chcete-li přidat další kontextový prostor k objektu poté, co ovladač volal metodu vytvoření objektu, ovladač může volat WdfObjectAllocateContext metoda-- což, jako jsou metody vytvoření objektu, přijímá WDF_OBJECT_ATTRIBUTES strukturu jako vstup.

Když rámec přiděluje kontextový prostor pro objekt, také nuluje tento kontextový prostor.

Když rámec nebo ovladač odstraní objekt rámce, rámec odstraní veškerý kontextový prostor objektu.

Pokud váš ovladač používá kontextový prostor k ukládání ukazatelů na vyrovnávací paměti, které ovladač přiděluje při vytváření objektu, měl by ovladač poskytnout funkci EvtCleanupCallback, která uvolní vyrovnávací paměti při odstranění objektu.

Chcete-li definovat kontextovou strukturu prostoru objektu a metodu přístupového objektu pro objekty, které ovladač vytvoří, musí ovladač použít následující kroky:

1. Definujte strukturu, která popisuje data, která chcete uložit. Pokud například chcete vytvořit kontextová data pro objekty zařízení ovladače, může ovladač definovat strukturu s názvem MY_DEVICE_CONTEXT.

2. Použijte makro WDF_DECLARE_CONTEXT_TYPE nebo WDF_DECLARE_CONTEXT_TYPE_WITH_NAME makro. Obě tato makra dělají toto:

   • Vytvoření a inicializace struktury WDF_OBJECT_CONTEXT_TYPE_INFO
   • Definujte přístupovou metodu, kterou ovladač později použije pro přístup ke kontextovému prostoru objektu. Návratová hodnota metody přístupového objektu je ukazatel na kontextový prostor objektu.

   Makro WDF_DECLARE_CONTEXT_TYPE vytvoří název metody příslušenství z názvu struktury. Pokud je například název kontextové struktury MY_DEVICE_CONTEXT, makro vytvoří metodu přístupového objektu s názvem WdfObjectGet_MY_DEVICE_CONTEXT.

   Makro WDF_DECLARE_CONTEXT_TYPE_WITH_NAME umožňuje zadat název metody přístupu. Můžete například zadat GetMyDeviceContext jako název metody kontextového přístupového objektu pro objekty zařízení.

3. Voláním WDF_OBJECT_ATTRIBUTES_INIT inicializujete strukturu WDF_OBJECT_ATTRIBUTES objektu.

4. Pomocí makra WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE nastavte ContextTypeInfo člen struktury WDF_OBJECT_ATTRIBUTES na adresu struktury WDF_OBJECT_CONTEXT_TYPE_INFO.

5. Zavolejte metodu vytvoření objektu, například WdfDeviceCreate.

Jakmile ovladač vytvoří objekt, ovladač může volat WdfObjectAllocateContext kdykoli a přidat tak další kontextový prostor k objektu.

Vzhledem k tomu, že kroky 1 a 2 definují globální datové struktury a vytvářejí rutinu pro volání ovladače, musí ovladač provést tyto kroky v oblasti ovladače, která deklaruje globální data – obvykle soubor hlaviček. Tyto kroky nesmí být dokončeny z rutin řidiče.

Řidič musí dokončit kroky 3, 4 a 5 v rámci rutiny ovladače, která vytváří objekt, například ve zpětné volací funkci EvtDriverDeviceAdd, která volá WdfDeviceCreate.

Rozhraní může vytvořit dva typy objektů – objekty žádosti pro rozhraní a objekty souboru rozhraní – pro váš ovladač. Ovladač může zaregistrovat kontextový prostor pro tyto objekty voláním WdfDeviceInitSetRequestAttributes a WdfDeviceInitSetFileObjectConfig, v uvedeném pořadí. Ovladač může také volat WdfObjectAllocateContext pro přidělení kontextového prostoru pro tyto objekty.

Po vytvoření objektu může ovladač získat ukazatel na kontextový prostor objektu pomocí některé z následujících technik:

• Pomocí makra WDF_DECLARE_CONTEXT_TYPE nebo WDF_DECLARE_CONTEXT_TYPE_WITH_NAME volejte metodu přístupu ke kontextu, kterou jste vytvořili v kroku 2 v předchozím postupu.

• Volání WdfObjectGetTypedContext, zadejte název struktury kontextu definované ovladačem.

Pokud má ovladač ukazatel kontextového prostoru, může najít objekt, do kterého kontextový prostor patří, voláním WdfObjectContextGetObject.