Funzione WdfWorkItemCreate (wdfworkitem.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfWorkItemCreate crea un oggetto work-item del framework, che successivamente può essere aggiunto alla coda dell'elemento di lavoro del sistema.

Sintassi

NTSTATUS WdfWorkItemCreate(
  [in]  PWDF_WORKITEM_CONFIG   Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFWORKITEM            *WorkItem
);

Parametri

[in] Config

Puntatore a una struttura di WDF_WORKITEM_CONFIG allocata dal chiamante che il driver deve avere già inizializzato chiamando WDF_WORKITEM_CONFIG_INIT.

[in] Attributes

Puntatore a una struttura WDF_OBJECT_ATTRIBUTES allocata dal chiamante che specifica gli attributi per l'oggetto elemento di lavoro.

[out] WorkItem

Puntatore a una variabile che riceve un handle al nuovo oggetto elemento di lavoro.

Valore restituito

WdfWorkItemCreate 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 fornito un parametro non valido.
STATUS_INVALID_DEVICE_REQUEST	L'elemento di lavoro padre dell'oggetto non è un oggetto dispositivo o il predecessore di un oggetto dispositivo.
STATUS_INSUFFICIENT_RESOURCES	Esistono risorse di sistema insufficienti per creare un oggetto elemento di lavoro.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Il membro AutomaticSerialization nella struttura WDF_WORKITEM_CONFIG a cui punta il parametro Config è TRUE, ma il livello di esecuzione dell'oggetto padre non è WdfExecutionLevelPassive.
STATUS_WDF_PARENT_NOT_SPECIFIED	Il parametro Attributes è NULL o il membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES che attributi specificano null.

Commenti

Dopo che un driver chiama WdfWorkItemCreate per creare un elemento di lavoro, in genere archivia informazioni specifiche dell'elemento nel contesto dell'oggetto elemento di lavoro. La funzione di callback evtWorkItem del driver, che esegue le attività dell'elemento di lavoro, può accedere a queste informazioni per determinare le attività che deve eseguire. Per altre informazioni sull'archiviazione delle informazioni nella memoria del contesto, vedere Framework Object Context Space.

Dopo aver archiviato le informazioni sull'elemento di lavoro, il driver deve chiamare WdfWorkItemEnqueue per aggiungere l'elemento di lavoro alla coda dell'elemento di lavoro del sistema. Quando un thread di lavoro di sistema diventa disponibile, il thread rimuove l'elemento di lavoro dalla coda e chiama la funzione di callback EvtWorkItem .

Quando il driver crea un oggetto elemento di lavoro, deve specificare un oggetto padre per l'oggetto elemento di lavoro nel membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES . L'oggetto padre deve essere un oggetto dispositivo framework o qualsiasi oggetto la cui catena di genitori porta a un oggetto dispositivo framework. Il framework eliminerà l'oggetto elemento di lavoro quando elimina l'oggetto device.

Per eliminare l'oggetto dell'elemento di lavoro precedente, il driver può chiamare WdfObjectDelete, come descritto in Using Framework Work Items (Uso degli elementi di lavoro di Framework).

Il driver può recuperare l'oggetto padre di un elemento di lavoro chiamando WdfWorkItemGetParentObject.

Se il driver fornisce funzioni di callback EvtCleanupCallback o EvtDestroyCallback per l'oggetto elemento di lavoro, si noti che il framework chiama queste funzioni di callback in IRQL = PASSIVE_LEVEL.

Per altre informazioni sugli elementi di lavoro, vedere Uso degli elementi di lavoro di Framework.

Esempio

Nell'esempio di codice seguente viene inizializzata una struttura WDF_OBJECT_ATTRIBUTES , inizializza una struttura WDF_WORKITEM_CONFIG e chiama WdfWorkItemCreate.

NTSTATUS  status = STATUS_SUCCESS;
PWORKER_ITEM_CONTEXT  context;
WDF_OBJECT_ATTRIBUTES  attributes;
WDF_WORKITEM_CONFIG  workitemConfig;
WDFWORKITEM  hWorkItem;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                       &attributes,
                                       WORKER_ITEM_CONTEXT
                                       );
attributes.ParentObject = FdoData->WdfDevice;

WDF_WORKITEM_CONFIG_INIT(
                         &workitemConfig,
                         CallbackFunction
                         );

status = WdfWorkItemCreate(
                            &workitemConfig,
                            &attributes,
                            &hWorkItem
                            );
if (!NT_SUCCESS(status)) {
    return status;
}

Requisiti

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

Vedi anche

WdfWorkItemEnqueue

Condividi tramite