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 |
|---|---|
|
È stato rilevato un parametro non valido. |
|
Il membro ContextTypeInfo della struttura di WDF_OBJECT_ATTRIBUTES specificata dal parametro ContextAttributes non è valido. |
|
Impossibile allocare lo spazio del contesto. |
|
Il driver ha già allocato lo spazio di contesto corrispondente al membro ContextTypeInfo della struttura WDF_OBJECT_ATTRIBUTES che ContextAttributes specifica. In questo caso, il puntatore nel Contesto parametro riceve un puntatore allo spazio di contesto esistente e non alloca spazio di contesto duplicato. |
|
L'oggetto specificato dal parametro handle viene eliminato. In questa situazione, il framework non alloca lo spazio del contesto. |
Questo metodo può anche restituire altri valori NTSTATUS .
Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.
Osservazioni:
In genere, i driver creano spazio di contesto oggetto specificando una struttura WDF_OBJECT_ATTRIBUTES quando chiamano il metodo di creazione di un oggetto framework, ad esempio WdfDeviceCreate.
Se si desidera 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 aver chiamato il metodo di creazione di un oggetto. Ogni chiamata a WdfObjectAllocateContext deve specificare un tipo di contesto diverso. (Il ContextTypeInfo membro della struttura WDF_OBJECT_ATTRIBUTES identifica il tipo di contesto.
Se il driver chiama WdfObjectAllocateContext più volte per un determinato oggetto, è possibile fornire EvtCleanupCallback e EvtDestroyCallback funzioni di callback per ogni contesto.
Quando si chiama WdfObjectAllocateContext, non specificare un ParentObject nella struttura WDF_OBJECT_ATTRIBUTES.
Quando il framework alloca lo spazio del 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.
Esempi
Nell'esempio di codice seguente viene creato lo spazio di contesto per un oggetto richiesta. Lo spazio di contesto si basa sulla struttura di 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 minima di KMDF | 1.0 |
| versione minima di UMDF | 2.0 |
| intestazione | wdfobject.h (include Wdf.h) |
| Biblioteca | Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
| IRQL | <=DISPATCH_LEVEL |
| regole di conformità DDI | DriverCreate(kmdf) |