Funzione WdfIoTargetSendReadSynchronously (wdfiotarget.h)

Articolo
08/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfIoTargetSendReadSynchronously compila una richiesta di lettura e la invia in modo sincrono a una destinazione di I/O.

Sintassi

NTSTATUS WdfIoTargetSendReadSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    OutputBuffer,
  [in, optional]  PLONGLONG                 DeviceOffset,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesRead
);

Parametri

[in] IoTarget

Handle a un oggetto di destinazione I/O locale o remoto ottenuto da una chiamata precedente a WdfDeviceGetIoTarget o WdfIoTargetCreate o da un metodo fornito da una destinazione di I/O specializzata.

[in, optional] Request

Handle per un oggetto richiesta framework. Questo parametro è facoltativo e può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguenti.

[in, optional] OutputBuffer

Puntatore a una struttura WDF_MEMORY_DESCRIPTOR allocata dal chiamante che descrive il buffer che riceverà i dati dal dispositivo. Questo parametro è facoltativo e può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguenti.

[in, optional] DeviceOffset

Puntatore a una posizione che specifica un offset iniziale per il trasferimento. La destinazione I/O , ovvero il driver inferiore successivo, definisce come usare questo valore. Ad esempio, i driver nello stack driver di un disco potrebbero specificare un offset dall'inizio del disco. La destinazione di I/O ottiene queste informazioni nel membro Parameters.Read.DeviceOffset della struttura WDF_REQUEST_PARAMETERS della richiesta. Questo puntatore è facoltativo. La maggior parte dei driver imposta questo puntatore su NULL.

[in, optional] RequestOptions

Puntatore a una struttura WDF_REQUEST_SEND_OPTIONS allocata dal chiamante che specifica le opzioni per la richiesta di lettura. Questo puntatore è facoltativo e può essere NULL.

[out, optional] BytesRead

Puntatore a una posizione che riceve il numero di byte letti, se l'operazione ha esito positivo. Questo puntatore è facoltativo e può essere NULL.

Valore restituito

Se l'operazione ha esito positivo, WdfIoTargetSendReadSynchronously restituisce dopo il completamento della richiesta di I/O e il valore restituito è il valore di stato di completamento della richiesta. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INFO_LENGTH_MISMATCH	Dimensioni della struttura WDF_REQUEST_SEND_OPTIONS a cui il parametro RequestOptions puntava non è corretto.
STATUS_INVALID_DEVICE_REQUEST	La richiesta di I/O è già stata accodata a una destinazione di I/O.
STATUS_INSUFFICIENT_RESOURCES	Il framework non è riuscito ad allocare le risorse di sistema (in genere memoria).
STATUS_IO_TIMEOUT	Il driver ha fornito un valore di timeout e la richiesta non è stata completata entro il tempo assegnato.
STATUS_REQUEST_NOT_ACCEPTED	Il pacchetto di richiesta I/O (IRP) che il parametro Request rappresenta non fornisce strutture IO_STACK_LOCATION sufficienti per consentire al driver di inoltrare la richiesta.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Commenti

Usare il metodo WdfIoTargetSendReadSynchronously per inviare richieste di lettura in modo sincrono. Per inviare richieste di lettura in modo asincrono, usare il metodo WdfIoTargetFormatRequestForRead , seguito dal metodo WdfRequestSend .

WdfIoTargetSendReadSynchronously non restituisce fino al completamento della richiesta, a meno che il driver non fornisca un valore di timeout nella struttura WDF_REQUEST_SEND_OPTIONS del parametro RequestOptions o a meno che non venga rilevato un errore.

È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure è possibile creare e inviare una nuova richiesta. In entrambi i casi, il framework richiede un oggetto request e uno spazio buffer.

Per inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O:

Specificare l'handle della richiesta ricevuta per il parametro Request .
Usare il buffer di output della richiesta ricevuta per il parametro OutputBuffer del metodo WdfIoTargetSendReadSynchronously.
Il driver deve chiamare WdfRequestRetrieveOutputMemory per ottenere un handle a un oggetto memoria del framework che rappresenta il buffer di output della richiesta. Il driver deve quindi posizionare tale handle nella struttura WDF_MEMORY_DESCRIPTOR fornita dal driver per il parametro OutputBuffer .

Per altre informazioni sull'inoltro di una richiesta di I/O, vedere Inoltro di richieste di I/O.

I driver spesso dividono le richieste di I/O ricevute in richieste più piccole inviate a una destinazione di I/O, in modo che il driver possa creare nuove richieste.

Per creare una nuova richiesta di I/O:

Specificare un handle di richiesta NULL per il parametro Request del metodo WdfIoTargetSendReadSynchronously, oppure creare un nuovo oggetto request e fornire il relativo handle:
- Se si specifica un handle di richiesta NULL , il framework usa un oggetto request interno. Questa tecnica è semplice da usare, ma il driver non può annullare la richiesta.
- Se si chiama WdfRequestCreate per creare uno o più oggetti richiesta, è possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. Questa tecnica consente all'evtDriverDevice del driverAggiungi la funzione di callback per preallocare gli oggetti di richiesta per un dispositivo. Inoltre, un altro thread driver può chiamare WdfRequestCancelSentRequest per annullare la richiesta, se necessario.
Il driver può specificare un parametroRequestOptions diverso da NULL, indipendentemente dal fatto che il driver fornisca un parametro non NULL o null Request. È possibile, ad esempio, usare il parametro RequestOptions per specificare un valore di timeout.
Fornire spazio buffer per il parametro OutputBuffer del metodo WdfIoTargetSendReadSynchronously.
Il driver può specificare questo spazio buffer come buffer allocato in locale, come handle WDFMEMORY o come elenco di descrittori di memoria (MDL). È possibile usare il metodo più pratico.

Se necessario, il framework converte la descrizione del buffer in un oggetto corretto per il metodo di destinazione di I/O per l'accesso ai buffer dati.

Sono disponibili le tecniche seguenti per specificare lo spazio del buffer:
- Specificare un buffer locale.
  Poiché WdfIoTargetSendReadSynchronously gestisce le richieste di I/O in modo sincrono, il driver può creare buffer di richiesta locali alla routine chiamante, come illustrato nell'esempio di codice seguente.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
MY_BUFFER_TYPE  MyBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&MemoryDescriptor,
                                  (PVOID) &MyBuffer,
                                  sizeof(MyBuffer));
```
- Specificare un handle WDFMEMORY.
  Chiamare WdfMemoryCreate o WdfMemoryCreatePreallocated per ottenere un handle per la memoria gestita dal framework, come illustrato nell'esempio di codice seguente.
```
WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
status = WdfMemoryCreate(NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL);
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(&MemoryDescriptor,
                                  MemoryHandle,
                                  NULL);
```
  In alternativa, il driver può chiamare WdfRequestRetrieveOutputMemory per ottenere un handle a un oggetto di memoria del framework che rappresenta un buffer di output della richiesta di I/O ricevuto, se si vuole che il driver passi il contenuto del buffer alla destinazione di I/O. Il driver non deve completare la richiesta di I/O ricevuta fino alla nuova richiesta che WdfIoTargetSendReadSynchronously invia alla destinazione di I/O è stata eliminata, riutilizzata o riformattata. (WdfIoTargetSendReadSynchronously incrementa il conteggio dei riferimenti dell'oggetto memoria. Eliminazione, riutilizzo o riformattamento di un oggetto request decrementa il numero di riferimenti dell'oggetto memoria.
- Specificare un MDL.
  I driver possono ottenere l'MDL associato a una richiesta di I/O ricevuta chiamando WdfRequestRetrieveOutputWdmMdl.

Alcune destinazioni di I/O accettano richieste di lettura con un buffer a lunghezza zero. Per tali destinazioni di I/O, il driver può specificare NULL per il parametro OutputBuffer .

Per informazioni sull'acquisizione di informazioni sullo stato dopo il completamento di una richiesta di I/O, vedere Recupero delle informazioni di completamento.

Per altre informazioni su WdfIoTargetSendReadSynchronously, vedere Invio di richieste di I/O a destinazioni di I/O generali.

Per altre informazioni sulle destinazioni di I/O, vedere Uso delle destinazioni di I/O.

Esempio

L'esempio di codice seguente crea un oggetto memoria del framework, inizializza una struttura WDF_MEMORY_DESCRIPTOR e passa la struttura a WdfIoTargetSendReadSynchronously. In questo esempio viene specificato NULL per l'handle dell'oggetto richiesta, pertanto il framework creerà un nuovo oggetto request per la destinazione di I/O.

WDF_MEMORY_DESCRIPTOR  MemoryDescriptor;
WDFMEMORY  MemoryHandle = NULL;
ULONG_PTR  bytesRead = NULL;

status = WdfMemoryCreate(
                         NULL,
                         NonPagedPool,
                         POOL_TAG,
                         MY_BUFFER_SIZE,
                         &MemoryHandle,
                         NULL
                         );
WDF_MEMORY_DESCRIPTOR_INIT_HANDLE(
                                  &MemoryDescriptor,
                                  MemoryHandle,
                                  NULL
                                  );
status = WdfIoTargetSendReadSynchronously(
                                          ioTarget,
                                          NULL,
                                          &MemoryDescriptor,
                                          NULL,
                                          NULL,
                                          &bytesRead
                                          );

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfiotarget.h (include Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), SyncReqSend(kmdf), WriteReqs(kmdf)