Funzione WdfIoTargetFormatRequestForIoctl (wdfiotarget.h)

[Si applica a KMDF e UMDF]

Il metodo WdfIoTargetFormatRequestForIoctl compila una richiesta di controllo del dispositivo per una destinazione di I/O, ma non invia la richiesta.

Sintassi

NTSTATUS WdfIoTargetFormatRequestForIoctl(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in]           ULONG             IoctlCode,
  [in, optional] WDFMEMORY         InputBuffer,
  [in, optional] PWDFMEMORY_OFFSET InputBufferOffset,
  [in, optional] WDFMEMORY         OutputBuffer,
  [in, optional] PWDFMEMORY_OFFSET OutputBufferOffset
);

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] Request

Handle per un oggetto richiesta framework. Per altre informazioni, vedere la sezione Osservazioni seguente.

[in] IoctlCode

Codice di controllo I/O (IOCTL) supportato dalla destinazione di I/O.

[in, optional] InputBuffer

Handle per un oggetto memoria del framework. Questo oggetto rappresenta un buffer che contiene dati che verranno inviati alla destinazione di I/O. Per altre informazioni, vedere la sezione Osservazioni seguente.

[in, optional] InputBufferOffset

Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset e lunghezza dei byte. Il framework usa questi valori per determinare l'indirizzo iniziale e la lunghezza, all'interno del buffer di input, per il trasferimento dei dati. Se questo puntatore è NULL, il trasferimento dei dati inizia all'inizio del buffer di input e la dimensione del trasferimento è la dimensione del buffer.

[in, optional] OutputBuffer

Handle per un oggetto memoria del framework. Questo oggetto rappresenta un buffer che riceverà i dati dalla destinazione di I/O. Per altre informazioni, vedere la sezione Osservazioni seguente.

[in, optional] OutputBufferOffset

Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset e lunghezza dei byte. Il framework usa questi valori per determinare l'indirizzo iniziale e la lunghezza, all'interno del buffer di output, per il trasferimento dei dati. Se questo puntatore è NULL, il trasferimento dei dati inizia all'inizio del buffer di output e le dimensioni del trasferimento sono le dimensioni del buffer.

Valore restituito

WdfIoTargetFormatRequestForIoctl restituisce STATUS_SUCCESS se l'operazione ha esito positivo. 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 WdfIoTargetFormatRequestForIoctl, seguito dal metodo WdfRequestSend, per inviare richieste di controllo del dispositivo in modo sincrono o asincrono. In alternativa, usare il metodo WdfIoTargetSendIoctlSynchronously per inviare le richieste di controllo del dispositivo in modo sincrono.

Per altre informazioni sulle richieste di controllo dei dispositivi, vedere Uso dei codici di controllo I/O.

È possibile inoltrare una richiesta di controllo del dispositivo 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 richiesta e uno spazio buffer.

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

1. Specificare l'handle della richiesta ricevuta per il parametro request WdfIoTargetFormatRequestForIoctl del metodo Request.
2. Usare il buffer di input della richiesta ricevuta per il parametro WdfIoTargetFormatRequestForIoctl del metodo InputBu ffer.

   Il driver deve chiamare WdfRequestRetrieveInputMemory per ottenere un handle a un oggetto memoria framework che rappresenta il buffer di input della richiesta e deve usare tale handle come valore per InputBuffer.

3. Usare il buffer di output della richiesta ricevuta per il parametro WdfIoTargetFormatRequestForIoctl del metodo OutputBuffer.

   Il driver deve chiamare WdfRequestRetrieveOutputMemory per ottenere un handle per il buffer di output della richiesta e deve usare tale handle come valore per OutputBuffer.

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. Creare un nuovo oggetto richiesta e specificare il relativo handle per il parametro Request del metodo Request di WdfIoTargetFormatRequestForIoct l.

   Chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta. È possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. Il driver EvtDriverDeviceAdd funzione di callback può preallocare oggetti richiesta per un dispositivo.

2. Specificare lo spazio del buffer e specificare l'handle del buffer per i parametri WdfIoTargetFormatRequestForIoctl del metodo InputBu ffer e OutputBuffer.

   Il driver deve specificare questo spazio buffer come handle WDFMEMORY per la memoria gestita dal framework. Il driver può eseguire una delle operazioni seguenti:

   • Chiamare WdfMemoryCreare o WdfMemoryCreatePreallocated per creare un nuovo buffer di memoria, se si vuole che il driver passi un nuovo buffer alla destinazione di I/O.
   • Chiamare WdfRequestRetrieveInputMemory o WdfRequestRetrieveOutputMemory per ottenere un handle all'oggetto memoria che rappresenta il buffer di una richiesta di I/O ricevuta, se si vuole che il driver passi il contenuto del buffer alla destinazione I/O.
   Si noti che se il driver chiama WdfRequestRetrieveInputMemory o WdfRequestRetrieveOutputMemory e passa l'handle di memoria a WdfIoTargetFormatRequestForIoctl, il driver non deve completare la richiesta di I/O ricevuta fino a quando il driver elimina, riutilizza o riformatta il nuovo oggetto richiesta creato dal driver. (WdfIoTargetFormatRequestForIoctl 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.

Più chiamate a WdfIoTargetFormatRequestForIoctl che usano la stessa richiesta non causano allocazioni di risorse aggiuntive. Pertanto, per ridurre la probabilità che WdfRequestCreate restituirà STATUS_INSUFFICIENT_RESOURCES, la funzione di callback evtDriverDeviceAdd funzione di callback può chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta per un dispositivo. Il driver può successivamente riutilizzare (chiamare WdfRequestReuse), riformattare (chiamare WdfIoTargetFormatRequestForIoctl) e inviare di nuovo (chiamare WdfRequestSend) ogni oggetto richiesta senza rischiare un valore restituito STATUS_INSUFFICIENT_RESOURCES da una chiamata successiva a WdfRequestCreate. Tutte le chiamate successive a WdfIoTargetFormatRequestForIoctl per l'oggetto richiesta riutilizzato restituiranno STATUS_SUCCESS, se i valori dei parametri non cambiano. Se il driver non chiama lo stesso metodo di formattazione delle richieste ogni volta, è possibile allocare risorse aggiuntive. Inoltre, se il codice di controllo I/O specifica un tipo di trasferimento di METHOD_BUFFERED, il framework deve allocare un buffer di sistema per ogni richiesta e tale allocazione potrebbe non riuscire a causa di risorse di memoria insufficienti.

Per informazioni su come ottenere informazioni sullo stato dopo il completamento di una richiesta di I/O, vedere ottenere informazioni di completamento.

Per altre informazioni su WdfIoTargetFormatRequestForIoctl, vedere l'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.

Esempi

Il codice seguente riutilizza un oggetto richiesta preallocato e oggetti memoria preallocati. L'esempio assegna buffer di input e output agli oggetti di memoria, formatta l'oggetto richiesta, registra una CompletionRoutine funzione di callback e invia la richiesta a una destinazione di I/O.

NTSTATUS
NICSendOidRequestToTargetAsync(
    IN WDFIOTARGET  IoTarget,
    IN WDFREQUEST  Request,
    IN PFILE_OBJECT  FileObject,
    IN ULONG  IoctlControlCode,
    IN OUT PVOID  InputBuffer,
    IN ULONG  InputBufferLength,
    IN OUT PVOID  OutputBuffer,
    IN ULONG  OutputBufferLength,
    OUT PULONG  BytesReadOrWritten
    )
{
    NTSTATUS  status;
    PREQUEST_CONTEXT  reqContext;
    WDF_REQUEST_REUSE_PARAMS  params;
    WDFMEMORY  inputMem, outputMem;
 
    WDF_REQUEST_REUSE_PARAMS_INIT(
                                  &params, 
                                  WDF_REQUEST_REUSE_NO_FLAGS, 
                                  STATUS_SUCCESS
                                  );
    status = WdfRequestReuse(Request, &params);
    if (!NT_SUCCESS(status)){
        return status;
    }

    reqContext = GetRequestContext(Request);

    inputMem = outputMem = NULL;
 
    if (InputBuffer != NULL) {
        status = WdfMemoryAssignBuffer(
                                       reqContext->InputMemory,
                                       InputBuffer, 
                                       InputBufferLength
                                       );
        if (!NT_SUCCESS(status)) {
             return status;
        }
        inputMem = reqContext->InputMemory;
    }

    if (OutputBuffer != NULL) {
        status = WdfMemoryAssignBuffer(
                                       reqContext->OutputMemory,
                                       OutputBuffer, 
                                       OutputBufferLength
                                       );
        if (!NT_SUCCESS(status)) {
            return status;
        }
        outputMem = reqContext->OutputMemory;
    }

    status = WdfIoTargetFormatRequestForIoctl(
                                              IoTarget,
                                              Request,
                                              IoctlControlCode,
                                              inputMem,
                                              NULL,
                                              outputMem,
                                              NULL
                                              );
    if (!NT_SUCCESS(status)) {
        return status;
    }

    WdfRequestSetCompletionRoutine(
                                   Request,
                                   NICSendOidRequestToTargetAsyncCompletionRoutine,
                                   BytesReadOrWritten
                                   );

    if (WdfRequestSend(
                       Request,
                       IoTarget,
                       WDF_NO_SEND_OPTIONS
                       ) == FALSE) {
        status = WdfRequestGetStatus(Request);
    }
    return status;
}

Requisiti

Vedere anche

EvtDriverDeviceAdd

WDFMEMORY_OFFSET

WdfDeviceGetIoTarget

WdfIoTargetCreare

WdfIoTargetFormatRequestForInternalIoctl

WdfIoTargetSendIoctlSynchronously

WdfMemoryCreare

WdfMemoryCreatePreallocated

WdfRequestCreare

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputMemory

WdfRequestReuse

WdfRequestSend