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 :
| Code de retour | Description |
|---|---|
|
Un paramètre non valide a été détecté. |
|
Membre ContextTypeInfo de la structure WDF_OBJECT_ATTRIBUTES que le paramètre ContextAttributes spécifié n’était pas valide. |
|
L’espace de contexte n’a pas pu être alloué. |
|
Le pilote a déjà alloué de l’espace de contexte qui correspond au membre ContextTypeInfo de la structure WDF_OBJECT_ATTRIBUTES spécifiée par ContextAttributes . Dans ce cas, le pointeur dans le paramètre Context reçoit un pointeur vers l’espace de contexte existant et n’alloue pas d’espace de contexte en double. |
|
L’objet spécifié par le paramètre Handle est en cours de suppression. Dans ce cas, l’infrastructure n’alloue pas d’espace de contexte. |
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
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| Version KMDF minimale | 1.0 |
| Version UMDF minimale | 2.0 |
| En-tête | wdfobject.h (inclure Wdf.h) |
| Bibliothèque | Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| Règles de conformité DDI | DriverCreate(kmdf) |