Fonction WdfObjectAllocateContext (wdfobject.h)

[S’applique à KMDF et UMDF]

La méthode WdfObjectAllocateContext alloue de l’espace de contexte pour un objet framework spécifié.

Syntaxe

NTSTATUS WdfObjectAllocateContext(
  [in]  WDFOBJECT              Handle,
  [in]  PWDF_OBJECT_ATTRIBUTES ContextAttributes,
  [out] PVOID                  *Context
);

Paramètres

[in] Handle

Handle d’un objet framework.

[in] ContextAttributes

Pointeur vers une structure de WDF_OBJECT_ATTRIBUTES fournie par l’appelant qui décrit l’espace de contexte.

[out] Context

Pointeur vers un emplacement qui reçoit un pointeur vers l’espace de contexte alloué.

Valeur retournée

WdfObjectAllocateContext retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

En règle générale, les pilotes créent un espace de contexte d’objet en spécifiant une structure WDF_OBJECT_ATTRIBUTES lorsqu’ils appellent la méthode de création d’un objet framework, telle que WdfDeviceCreate.

Si vous souhaitez que votre pilote alloue plusieurs types d’espace de contexte à certains de ses objets, le pilote peut appeler WdfObjectAllocateContext une ou plusieurs fois après avoir appelé la méthode de création d’un objet. Chaque appel à WdfObjectAllocateContext doit spécifier un type de contexte différent. (Le membre ContextTypeInfo de la structure WDF_OBJECT_ATTRIBUTES identifie le type de contexte.)

Si votre pilote appelle WdfObjectAllocateContext plusieurs fois pour un objet donné, vous pouvez fournir des fonctions de rappel EvtCleanupCallback et EvtDestroyCallback distinctes pour chaque contexte.

Lorsque vous appelez WdfObjectAllocateContext, ne spécifiez pas de ParentObject dans la structure WDF_OBJECT_ATTRIBUTES .

Lorsque l’infrastructure alloue de l’espace de contexte pour un objet, elle l’initialise également à zéro.

Pour plus d’informations sur l’espace de contexte d’objet, consultez Espace de contexte d’objet Framework.

Pour plus d’informations sur les règles de nettoyage d’une hiérarchie d’objets framework, consultez Framework Object Life Cycle.

Exemples

L’exemple de code suivant crée un espace de contexte pour un objet de requête. L’espace de contexte est basé sur la structure REQUEST_CONTEXT de l’exemple.

typedef struct _REQUEST_CONTEXT {
  WDFMEMORY InputMemoryBuffer;
  WDFMEMORY OutputMemoryBuffer;
} REQUEST_CONTEXT, *PREQUEST_CONTEXT;

PREQUEST_CONTEXT  reqContext = NULL;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                        &attributes,
                                        REQUEST_CONTEXT
                                        );
status = WdfObjectAllocateContext(
                                  Request,
                                  &attributes,
                                  &reqContext
                                  );

Configuration requise

Voir aussi

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WdfDeviceCreate