Funzione WdfObjectAllocateContext (wdfobject.h)

[Si applica a KMDF e UMDF]

Il metodo WdfObjectAllocateContext alloca lo spazio del contesto per un oggetto framework specificato.

Sintassi

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

Parametri

[in] Handle

Handle per un oggetto framework.

[in] ContextAttributes

Puntatore a una struttura di WDF_OBJECT_ATTRIBUTES fornita dal chiamante che descrive lo spazio del contesto.

[out] Context

Puntatore a una posizione che riceve un puntatore allo spazio di contesto allocato.

Valore restituito

WdfObjectAllocateContext restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_OBJECT_NAME_INVALID	Membro ContextTypeInfo della struttura WDF_OBJECT_ATTRIBUTES specificato dal parametro ContextAttributes non valido.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare spazio di contesto.
STATUS_OBJECT_NAME_EXISTS	Il driver ha già allocato lo spazio di contesto corrispondente al membro ContextTypeInfo della struttura WDF_OBJECT_ATTRIBUTES specificata da ContextAttributes . In questo caso, il puntatore nel parametro Context riceve un puntatore allo spazio di contesto esistente e non alloca spazio di contesto duplicato.
STATUS_DELETE_PENDING	Oggetto specificato dal parametro Handle . In questo caso, il framework non alloca spazio del contesto.

 

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Commenti

In genere, i driver creano spazio contesto oggetto specificando una struttura WDF_OBJECT_ATTRIBUTES quando chiamano il metodo di creazione di un oggetto framework, ad esempio WdfDeviceCreate.

Se si vuole che il driver allochi più di un tipo di spazio di contesto ad alcuni dei relativi oggetti, il driver può chiamare WdfObjectAllocateContext una o più volte dopo che ha chiamato il metodo di creazione di un oggetto. Ogni chiamata a WdfObjectAllocateContext deve specificare un tipo di contesto diverso. Il membro ContextTypeInfo della struttura WDF_OBJECT_ATTRIBUTES identifica il tipo di contesto.

Se il driver chiama WdfObjectAllocateContext più volte per un determinato oggetto, è possibile fornire funzioni di callback EvtCleanupCallback e EvtDestroyCallback separate per ogni contesto.

Quando si chiama WdfObjectAllocateContext, non specificare un oggetto ParentObject nella struttura WDF_OBJECT_ATTRIBUTES .

Quando il framework alloca lo spazio di contesto per un oggetto, inizializza anche lo spazio del contesto.

Per altre informazioni sullo spazio del contesto dell'oggetto, vedere Framework Object Context Space.

Per altre informazioni sulle regole di pulizia per una gerarchia di oggetti framework, vedere Framework Object Life Cycle.

Esempio

Nell'esempio di codice seguente viene creato lo spazio di contesto per un oggetto richiesta. Lo spazio di contesto è basato sulla struttura REQUEST_CONTEXT dell'esempio.

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
                                  );

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfobject.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf)

Vedi anche

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WdfDeviceCreate