Condividi tramite


Funzione WdfIoTargetFormatRequestForInternalIoctl (wdfiotarget.h)

[Si applica solo a KMDF]

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

Sintassi

NTSTATUS WdfIoTargetFormatRequestForInternalIoctl(
  [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 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 I/O specializzata.

[in] Request

Handle per un oggetto richiesta framework. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in] IoctlCode

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

[in, optional] InputBuffer

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

[in, optional] InputBufferOffset

Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset e lunghezza di 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 framework. Questo oggetto rappresenta un buffer che riceverà i dati dalla destinazione di I/O. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, optional] OutputBufferOffset

Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset e lunghezza di 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 la dimensione del trasferimento è la dimensione del buffer.

Valore restituito

WdfIoTargetFormatRequestForInternalIoctl 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 rilevato un parametro non valido.
STATUS_INVALID_DEVICE_REQUEST
La lunghezza del trasferimento è maggiore della lunghezza del buffer oppure 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_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

Utilizzare il metodo WdfIoTargetFormatRequestForInternalIoctl , seguito dal metodo WdfRequestSend , per inviare richieste di controllo del dispositivo interno in modo sincrono o asincrono. In alternativa, usare il metodo WdfIoTargetSendInternalIoctlSynchronously per inviare richieste di controllo del dispositivo interno in modo sincrono.

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

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

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

  1. Specificare l'handle della richiesta ricevuta per il parametro Request del metodo WdfIoTargetFormatRequestForInternalIoctl.
  2. Usare il buffer di input della richiesta ricevuta per il parametro InputBuffer del metodo WdfIoTargetFormatRequestForInternalIoctl.

    Il driver deve chiamare WdfRequestRetrieveInputMemory per ottenere un handle nel 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 OutputBuffer del metodo WdfIoTargetFormatRequestForInternalIoctl.

    Il driver deve chiamare WdfRequestRetrieveOutputMemory per ottenere un handle nel buffer di output della richiesta e deve usare tale handle come valore per 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:

  1. Creare un nuovo oggetto request e specificare il relativo handle per il parametro Request del metodo WdfIoTargetFormatRequestForInternalIoctl.

    Chiamare WdfRequestCrea per preallocare uno o più oggetti richiesta. È possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. La funzione di callback EvtDriverDevice del driver può preallocare gli oggetti di richiesta per un dispositivo.

  2. Fornire spazio del buffer e fornire l'handle del buffer per i parametri InputBuffer e OutputBuffer del metodo WdfIoTargetFormatRequestForInternalIoctl.

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

    Si noti che se il driver chiama WdfRequestRetrieveInputMemory o WdfRequestRetrieveOutputMemory e passa l'handle di memoria a WdfIoTargetFormatRequestForInternalIoctl, 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. (WdfIoTargetFormatRequestForInternalIoctl incrementa il conteggio dei riferimenti dell'oggetto memoria. Eliminazione, riutilizzo o riformattamento di un oggetto request decrementa il numero di riferimenti dell'oggetto memoria.
Dopo che un driver chiama WdfIoTargetFormatRequestForInternalIoctl per formattare una richiesta di controllo del dispositivo, il driver deve chiamare WdfRequestSend per inviare la richiesta (in modo sincrono o asincrono) a una destinazione di I/O.

Più chiamate a WdfIoTargetFormatRequestForInternalIoctl che usano la stessa richiesta non causano allocazioni di risorse aggiuntive. Pertanto, per ridurre la possibilità che WdfRequestCreate restituirà STATUS_INSUFFICIENT_RESOURCES, la funzione evtDriverDeviceAdd callback del driver può chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta per un dispositivo. Il driver può successivamente riutilizzare (chiamare WdfRequestReuse), riformatare (chiamare WdfIoTargetFormatRequestForInternalIoctl) e inviare nuovamente (chiamare WdfRequestSend) ogni oggetto richiesta senza rischiare un valore restituito STATUS_INSUFFICIENT_RESOURCES da una chiamata successiva a WdfRequestCreate. Tutte le chiamate successive a WdfIoTargetFormatRequestForInternalIoctl per l'oggetto richiesta riutilizzato restituiranno STATUS_SUCCESS, se i valori dei parametri non cambiano. Tuttavia, 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 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 WdfIoTargetFormatRequestForInternalIoctl, 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

Nell'esempio di codice seguente viene creato un oggetto memoria framework figlio di un oggetto request. L'esempio ottiene quindi il buffer che l'oggetto memoria contiene e inizializza il buffer. L'esempio formatta quindi la richiesta, imposta una funzione di callback Di completamentoRoutine e invia la richiesta a una destinazione di I/O.

WDF_OBJECT_ATTRIBUTES memoryObjAttr;
WDFMEMORY memory;
NTSTATUS status;
IOCTL_DATA *pIoctlData;

WDF_OBJECT_ATTRIBUTES_INIT(&memoryObjAttr);
memoryObjAttr.ParentObject = Request;

status = WdfMemoryCreate(
                         &memoryObjAttr,
                         NonPagedPool,
                         0,
                         sizeof(IOCTL_DATA),
                         &memory,
                         NULL
                         );
if (!NT_SUCCESS(status)) {
    goto Done;
}
pIoctlData = WdfMemoryGetBuffer(
                                memory,
                                NULL
                                );
RtlZeroMemory(
              pIoctlData,
              sizeof(IOCTL_DATA)
              );
pIoctlData->Member1 = MY_DATA;

status = WdfIoTargetFormatRequestForInternalIoctl(
                                                  IoTarget,
                                                  Request,
                                                  IOCTL_INTERNAL_GET_MY_DATA,
                                                  memory,
                                                  NULL,
                                                  WDF_NO_HANDLE,
                                                  NULL
                                                  );

if (!NT_SUCCESS(status)) {
    goto Done;
}

WdfRequestSetCompletionRoutine(
                               Request,
                               MyRequestCompletion,
                               NULL
                               );

if (WdfRequestSend(
                   Request,
                   IoTarget,
                   NULL
                   ) == FALSE) {
    status = WdfRequestGetStatus(Request);
}
else {
    status = STATUS_SUCCESS;
}

Requisiti

Requisito Valore
Piattaforma di destinazione Universale
Versione KMDF minima 1,0
Intestazione wdfiotarget.h (include Wdf.h)
Libreria Wdf01000.sys (vedere Framework Library Versioning).
IRQL <=DISPATCH_LEVEL
Regole di conformità DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)

Vedi anche

EvtDriverDeviceAdd

WDFMEMORY_OFFSET

WdfDeviceGetIoTarget

WdfIoTargetCreate

WdfIoTargetFormatRequestForIoctl

WdfIoTargetSendInternalIoctlSynchronously

WdfIoTargetSendIoctlSynchronously

WdfMemoryCreate

WdfMemoryCreatePreallocated

WdfRequestCreate

WdfRequestRetrieveInputMemory

WdfRequestRetrieveOutputMemory

WdfRequestReuse

WdfRequestSend