Funzione WdfIoTargetSendWriteSynchronously (wdfiotarget.h)

[Si applica a KMDF e UMDF]

Il metodo WdfIoTargetSendWriteSynchronously compila una richiesta di scrittura e lo invia in modo sincrono a una destinazione di I/O.

Sintassi

NTSTATUS WdfIoTargetSendWriteSynchronously(
  [in]            WDFIOTARGET               IoTarget,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    InputBuffer,
  [in, optional]  PLONGLONG                 DeviceOffset,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [out, optional] PULONG_PTR                BytesWritten
);

Parametri

[in] IoTarget

Handle per un oggetto di destinazione I/O locale o remoto ottenuto da una chiamata precedente a WdfDeviceGetIoTarget o WdfIoTargetCreateo 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 seguente.

[in, optional] InputBuffer

Puntatore a una struttura di WDF_MEMORY_DESCRIPTOR allocata dal chiamante che descrive il buffer che contiene dati che verranno scritti nel dispositivo. Questo parametro è facoltativo e può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguente.

[in, optional] DeviceOffset

Puntatore a una posizione che specifica un offset iniziale per il trasferimento. La destinazione di I/O , ovvero il driver inferiore successivo, definisce come usare questo valore. Ad esempio, i driver nello stack di driver di un disco potrebbero specificare un offset dall'inizio del disco. La destinazione di I/O ottiene queste informazioni nel Parameters.Write.DeviceOffset membro 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. Questo puntatore è facoltativo e può essere NULL. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguente.

[out, optional] BytesWritten

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

Valore restituito

Se l'operazione ha esito positivo, WdfIoTargetSendWriteSynchronously 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:

Questo metodo potrebbe anche restituire altri valori NTSTATUS .

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

Osservazioni

Usare il metodo WdfIoTargetSendWriteSynchronously per inviare richieste di scrittura in modo sincrono. Per inviare richieste di scrittura in modo asincrono, usare il metodo WdfIoTargetFormatRequestForWrite, seguito dal metodo WdfRequestSend.

WdfIoTargetSendWriteSynchronously non restituisce fino al completamento della richiesta, a meno che il driver non fornisca un valore di timeout nella struttura RequestOptions parametro WDF_REQUEST_SEND_OPTIONS 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 creare e inviare una nuova richiesta. In entrambi i casi, il framework richiede un oggetto richiesta e uno spazio buffer.

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

1. Specificare l'handle della richiesta ricevuta per il parametro request Request del metodo WdfIoTargetSendWriteSynchronously.
2. Usare il buffer di input della richiesta ricevuta per il parametro inputBuffer del metodo WdfIoTargetSendWriteSynchronous ly.

   Il driver deve chiamare WdfRequestRetrieveInputMemory per ottenere un handle a un oggetto memoria framework che rappresenta il buffer di input della richiesta e quindi posizionare tale handle nella struttura WDF_MEMORY_DESCRIPTOR fornita dal driver per il parametro InputBuffer.

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:

1. Specificare un handle di richiesta NULL per il parametro WdfIoTargetSendWriteSynchronously request del metodo oppure creare un nuovo oggetto richiesta e specificarne l'handle:
   • Se si specifica un handle di richiesta NULL , il framework usa un oggetto richiesta 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 al driver di EvtDriverDeviceAdd funzione di callback per preallocare gli oggetti richiesta per un dispositivo. Inoltre, un altro thread del driver può chiamare WdfRequestCancelSentRequest per annullare la richiesta, se necessario.

   Il driver può specificare un parametro nullNULLnull, indipendentemente dal fatto che il driver fornisca un NULL nono un parametro RequestNULL . È ad esempio possibile usare il parametro RequestOptions per specificare un valore di timeout.

2. Specificare lo spazio del buffer per il parametro inputBuffer del metodo WdfIoTargetSendWriteSynchronously.

   Il driver può specificare questo spazio buffer come buffer allocato localmente, come handle WDFMEMORY o come elenco di descrittori di memoria (MDL). È possibile usare qualsiasi metodo sia più pratico.

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

   Sono disponibili le tecniche seguenti per specificare lo spazio del buffer:

   • Fornire un buffer locale.

     Poiché WdfIoTargetSendWriteSynchronously gestisce le richieste di I/O in modo sincrono, il driver può creare buffer di richiesta locali per la 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 WdfMemoryCreare 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 WdfRequestRetrieveInputMemory per ottenere un handle a un oggetto memoria del framework che rappresenta il buffer di input di una richiesta di I/O ricevuta, 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 a quando la nuova richiesta che WdfIoTargetSendWriteSynchronously inviato alla destinazione di I/O non è stata eliminata, riutilizzata o riformattata. (WdfIoTargetSendWriteSynchronously incrementa il conteggio dei riferimenti dell'oggetto memoria. L'eliminazione, il riutilizzo o la riformattazione di un oggetto richiesta decrementa il conteggio dei riferimenti dell'oggetto memoria.

   • Specificare un MDL.

     I driver possono ottenere il file MDL associato a una richiesta di I/O ricevuta chiamando WdfRequestRetrieveInputWdmMdl.

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

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