Funzione WdfIoTargetFormatRequestForInternalIoctlOthers (wdfiotarget.h)
[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
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] 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
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] 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 |
|---|---|
|
È stato rilevato un parametro non valido. |
|
La lunghezza del trasferimento è maggiore della lunghezza del buffer oppure la richiesta di I/O è già stata accodata a una destinazione di I/O. |
|
Il framework non è riuscito ad allocare risorse di sistema (in genere memoria). |
|
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.
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.
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) |
Vedi anche
WdfIoTargetSendInternalIoctlOthersSynchronously