Funzione WdfIoTargetFormatRequestForInternalIoctlOthers (wdfiotarget.h)

Articolo
08/08/2023

[Si applica solo a KMDF]

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

Sintassi

NTSTATUS WdfIoTargetFormatRequestForInternalIoctlOthers(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in]           ULONG             IoctlCode,
  [in, optional] WDFMEMORY         OtherArg1,
  [in, optional] PWDFMEMORY_OFFSET OtherArg1Offset,
  [in, optional] WDFMEMORY         OtherArg2,
  [in, optional] PWDFMEMORY_OFFSET OtherArg2Offset,
  [in, optional] WDFMEMORY         OtherArg4,
  [in, optional] PWDFMEMORY_OFFSET OtherArg4Offset
);

Parametri

[in] IoTarget

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

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

[in] IoctlCode

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

[in, optional] OtherArg1

Handle per un oggetto memoria del framework. Questo oggetto rappresenta un buffer utilizzato dal driver per informazioni sul contesto specifiche della richiesta e definite dal driver. Per ulteriori informazioni, vedere la sezione Osservazioni successiva. Questo parametro è facoltativo e può essere NULL.

[in, optional] OtherArg1Offset

Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset di byte e lunghezza. I driver possono usare questi valori per specificare l'indirizzo iniziale e la lunghezza di un segmento dell'area di contesto specificata da OtherArg1. Questo parametro è facoltativo e può essere NULL.

[in, optional] OtherArg2

[in, optional] OtherArg2Offset

Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset di byte e lunghezza. I driver possono usare questi valori per specificare l'indirizzo iniziale e la lunghezza di un segmento dell'area di contesto specificata da OtherArg2. Questo parametro è facoltativo e può essere NULL.

[in, optional] OtherArg4

[in, optional] OtherArg4Offset

Puntatore a una struttura WDFMEMORY_OFFSET allocata dal chiamante che fornisce valori facoltativi di offset di byte e lunghezza. I driver possono usare questi valori per specificare l'indirizzo iniziale e la lunghezza di un segmento dell'area di contesto specificata da OtherArg4. Questo parametro è facoltativo e può essere NULL.

Valore restituito

WdfIoTargetFormatRequestForInternalIoctlOthers 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 risorse di sistema (in genere memoria).
STATUS_REQUEST_NOT_ACCEPTED	Il pacchetto di richiesta di I/O rappresentato dal parametro Request non fornisce strutture IO_STACK_LOCATION sufficienti per consentire al driver di inoltrare la richiesta.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

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

Commenti

Utilizzare il metodo WdfIoTargetFormatRequestForInternalIoctlOthers , seguito dal metodo WdfRequestSend , per inviare richieste di controllo del dispositivo interno non standard in modo sincrono o asincrono. In alternativa, usare il metodo WdfIoTargetSendInternalIoctlOthersSynchronously per inviare richieste di controllo dei dispositivi interne non standard in modo sincrono.

È possibile inoltrare una richiesta di controllo del dispositivo interno non standard 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 interno non standard ricevuta dal driver in una coda di I/O:

Specificare l'handle della richiesta ricevuta per il parametro Request del metodo WdfIoTargetFormatRequestForInternalIoctlOthers.
Usare le informazioni di contesto della richiesta ricevuta per i parametri OtherArg1, OtherArg2, OtherArg2, OtherArg2 e OtherArg4 del metodo WdfIoTargetFormatRequestForInternalIoctlOthers.
Per ottenere questi valori di parametro, il driver deve chiamare WdfRequestGetParameters e usare il membro DeviceIoControl della struttura WDF_REQUEST_PARAMETERS restituita.

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:

Creare un nuovo oggetto richiesta e specificare il relativo handle per il parametro Request del metodo WdfIoTargetFormatRequestForInternalIoctlOthers.
Chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta. È possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. La funzione di callback EvtDriverDeviceAdd del driver può preallocare oggetti richiesta per un dispositivo.
Specificare i buffer di contesto, se la richiesta li richiede e fornire handle del buffer per i parametri WdfIoTargetFormatRequestForInternalIoctlOthers del metodo OtherArg1, OtherArg2 e OtherArg4 .
Il driver deve specificare questo spazio buffer come handle WDFMEMORY per la memoria gestita dal framework. Per ottenere handle WDFMEMORY, il driver chiama WdfMemoryCreate o WdfMemoryCreatePreallocated.

Dopo che un driver chiama WdfIoTargetFormatRequestForInternalIoctlOthers 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 WdfIoTargetFormatRequestForInternalIoctlOthers che usano la stessa richiesta non causano allocazioni di risorse aggiuntive. Pertanto, per ridurre la probabilità che WdfRequestCreate restituisca STATUS_INSUFFICIENT_RESOURCES, la funzione di callback EvtDriverDeviceAdd del driver può chiamare WdfRequestCreate per preallocare uno o più oggetti richiesta per un dispositivo. Il driver può successivamente riutilizzare (chiamare WdfRequestReuse), riformattare (chiamare WdfIoTargetFormatRequestForInternalIoctlOthers) e inviare nuovamente (chiamare WdfRequestSend) ogni oggetto richiesta senza rischiare un valore restituito STATUS_INSUFFICIENT_RESOURCES da una chiamata successiva a WdfRequestCreate. Se il driver non chiama lo stesso metodo di formattazione delle richieste ogni volta, è possibile allocare risorse aggiuntive. Tutte le chiamate successive a WdfIoTargetFormatRequestForInternalIoctlOthers per l'oggetto richiesta riutilizzato restituiranno STATUS_SUCCESS, se i valori dei parametri non cambiano.

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 WdfIoTargetFormatRequestForInternalIoctlOthers, 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, viene ottenuto il buffer contenuto dall'oggetto memory e viene inizializzato il buffer. L'esempio formatta quindi la richiesta, imposta una funzione di callback CompletionRoutine e invia la richiesta a una destinazione di I/O.

PIRB pIrb;
WDFMEMORY memory;
NTSTATUS status;

status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         sizeof(IRB),
                         &memory,
                         NULL
                         );
if (!NT_SUCCESS(status)) {
    goto Done;
}
pIrb = WdfMemoryGetBuffer(
                          memory,
                          NULL
                          );

pIrb->FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
pIrb->Flags = 0;
pIrb->u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
pIrb->u.AllocateAddressRange.fulFlags = fulFlags;
pIrb->u.AllocateAddressRange.nLength = nLength;
pIrb->u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
pIrb->u.AllocateAddressRange.fulAccessType = fulAccessType;
pIrb->u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
pIrb->u.AllocateAddressRange.Callback = NULL;
pIrb->u.AllocateAddressRange.Context = NULL;
pIrb->u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
pIrb->u.AllocateAddressRange.FifoSListHead = NULL;
pIrb->u.AllocateAddressRange.FifoSpinLock = NULL;
pIrb->u.AllocateAddressRange.AddressesReturned = 0;
pIrb->u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
pIrb->u.AllocateAddressRange.DeviceExtension = deviceExtension;

status = WdfIoTargetFormatRequestForInternalIoctlOthers(
                                                        IoTarget,
                                                        Request,
                                                        IOCTL_1394_CLASS,
                                                        memory,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        NULL,
                                                        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 Controllo delle versioni della libreria framework).
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)