Funzione WdfRequestCreate (wdfrequest.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfRequestCreate crea un oggetto richiesta framework vuoto.

Sintassi

NTSTATUS WdfRequestCreate(
  [in, optional] PWDF_OBJECT_ATTRIBUTES RequestAttributes,
  [in, optional] WDFIOTARGET            IoTarget,
  [out]          WDFREQUEST             *Request
);

Parametri

[in, optional] RequestAttributes

Puntatore a una struttura di WDF_OBJECT_ATTRIBUTES allocata dal chiamante che specifica gli attributi dell'oggetto richiesta. Questo parametro è facoltativo e può essere WDF_NO_OBJECT_ATTRIBUTES.

[in, optional] IoTarget

Handle per un oggetto di destinazione di I/O del framework. Questo parametro è facoltativo e può essere NULL. Se non NULL,WdfRequestCreate verifica che il driver possa eventualmente inviare la richiesta alla destinazione di I/O specificata.

[out] Request

Puntatore a una posizione che riceve un handle a un oggetto richiesta framework.

Valore restituito

WdfRequestCreate 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	Un parametro di input non è valido.
STATUS_INSUFFICIENT_RESOURCES	Esistono risorse di sistema insufficienti per completare l'operazione.
STATUS_REQUEST_NOT_ACCEPTED	La matrice dello stack di I/O della richiesta non è abbastanza grande per consentire al driver di inviare la richiesta alla destinazione I/O specificata.

Per un elenco di valori restituiti aggiuntivi, vedere Errori di creazione di oggetti Framework.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Commenti

Un driver basato su framework può chiamare WdfRequestCreate per creare una nuova richiesta che il driver passa successivamente ad altre funzioni del framework per l'inizializzazione. Ad esempio, un driver per un dispositivo USB potrebbe chiamare WdfUsbTargetPipeFormatRequestForRead per formattare una nuova richiesta di lettura.

Un driver basato su framework che comunica con i driver WDM potrebbe specificare il contenuto di una richiesta chiamando WdfRequestCreateFromIrp.

Se un driver chiama WdfRequestCreate per creare un oggetto request, non deve chiamare WdfRequestComplete per l'oggetto request. Il driver deve invece chiamare WdfObjectDelete al termine dell'uso dell'oggetto request. Per altre informazioni, vedere Completamento delle richieste di I/O.

Per impostazione predefinita, il padre del nuovo oggetto request è l'oggetto driver del framework creato dal metodo WdfDriverCreate . È possibile usare il membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES per specificare un elemento padre diverso. Il framework elimina l'oggetto request quando elimina l'oggetto padre. Se il driver non modifica l'elemento padre predefinito, il driver deve eliminare l'oggetto richiesta al termine dell'uso dell'oggetto; in caso contrario, l'oggetto request rimarrà fino a quando il gestore di I/O scarica il driver.

Per altre informazioni sulla chiamata a WdfRequestCreate, vedere Creazione di oggetti richiesta framework.

Esempio

L'esempio di codice seguente crea un oggetto di destinazione I/O, inizializza una struttura WDF_OBJECT_ATTRIBUTES e chiama WdfRequestCreate. L'elemento padre della nuova richiesta è l'oggetto di destinazione I/O.

WDF_OBJECT_ATTRIBUTES  attributes;
WDFREQUEST newRequest;
WDFIOTARGET ioTarget;
...
status = WdfIoTargetCreate(
                           Device,
                           WDF_NO_OBJECT_ATTRIBUTES,
                           &ioTarget
                           );
  ...
WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = ioTarget;

status = WdfRequestCreate(
                          &attributes,
                          ioTarget,
                          &newRequest
                          );

if (!NT_SUCCESS(status)) {
    return status;
}

Requisiti

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