Funzione WdfIoTargetSendInternalIoctlOthersSynchronously (wdfiotarget.h)
[Si applica solo a KMDF]
Il metodo WdfIoTargetSendInternalIoctlOthersSynchronously compila una richiesta di controllo del dispositivo interno non standard e lo invia in modo sincrono a una destinazione di I/O.
Sintassi
NTSTATUS WdfIoTargetSendInternalIoctlOthersSynchronously(
[in] WDFIOTARGET IoTarget,
[in, optional] WDFREQUEST Request,
[in] ULONG IoctlCode,
[in, optional] PWDF_MEMORY_DESCRIPTOR OtherArg1,
[in, optional] PWDF_MEMORY_DESCRIPTOR OtherArg2,
[in, optional] PWDF_MEMORY_DESCRIPTOR OtherArg4,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[out, optional] PULONG_PTR BytesReturned
);
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, optional] Request
Handle per un oggetto richiesta framework. Questo parametro è facoltativo e può essere NULL. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.
[in] IoctlCode
Codice di controllo I/O (IOCTL) supportato dalla destinazione I/O.
[in, optional] OtherArg1
Puntatore a una struttura WDF_MEMORY_DESCRIPTOR che descrive un buffer di memoria contenente informazioni di contesto. Questo parametro è facoltativo e può essere NULL.
[in, optional] OtherArg2
Puntatore a una struttura WDF_MEMORY_DESCRIPTOR che descrive un buffer di memoria contenente informazioni di contesto. Questo parametro è facoltativo e può essere NULL.
[in, optional] OtherArg4
Puntatore a una struttura WDF_MEMORY_DESCRIPTOR che descrive un buffer di memoria contenente informazioni di contesto. Questo parametro è facoltativo e può essere 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 ulteriori informazioni, vedere la sezione Osservazioni successiva.
[out, optional] BytesReturned
Puntatore a una posizione che riceve informazioni(ad esempio il numero di byte trasferiti) che un altro driver fornisce quando completa la richiesta chiamando WdfRequestCompleteWithInformation. Questo puntatore è facoltativo e può essere NULL.
Valore restituito
Se l'operazione ha esito positivo, WdfIoTargetSendInternalIoctlOthersSynchronously restituisce dopo il completamento della richiesta di controllo del dispositivo interno e il valore restituito è il valore di stato di completamento della richiesta. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:
Codice restituito | Descrizione |
---|---|
|
È stato rilevato un parametro non valido. |
|
Dimensioni della struttura WDF_REQUEST_SEND_OPTIONS a cui il parametro RequestOptions puntava non è corretto. |
|
La richiesta è già stata accodata a una destinazione di I/O. |
|
Il framework non è riuscito ad allocare le risorse di sistema (in genere memoria). |
|
Il driver ha fornito un valore di timeout e la richiesta non è stata completata entro il tempo assegnato. |
|
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
Una richiesta di controllo del dispositivo interno non standard usa un codice IOCTL per identificare l'operazione da eseguire, ma la richiesta non usa i buffer di input e output standard usati da altre richieste di controllo del dispositivo interno. Se si crea un set di driver di interazione, è possibile definire come questo set di driver usa gli argomenti della richiesta: OtherArg1, OtherArg2 e OtherArg4.
Non esiste alcun parametro denominato OtherArg3 perché il framework associa questi parametri ai membri Argument1, Argument2 e Argument4 dell'unione Other.Parameters nella struttura di IO_STACK_LOCATION del driver. Il membro Argument3 in tale unione riceve il valore dal parametro IoctlCode , pertanto non è disponibile per altri valori forniti dal driver.
Usare il metodo WdfIoTargetSendInternalIoctlOthersSynchronously per inviare richieste di controllo del dispositivo interno non standard sincrono. Per inviare richieste di controllo del dispositivo interno in modo asincrono, usare WdfIoTargetFormatRequestForInternalIoctlOthers, seguito da WdfRequestSend.
Per altre informazioni sulle richieste di controllo dei dispositivi interni, vedere Uso dei codici di controllo I/O.
Il metodo WdfIoTargetSendInternalIoctlOthersSynchronously non restituisce finché la richiesta non viene completata, a meno che il driver non fornisca un valore di timeout nella struttura WDF_REQUEST_SEND_OPTIONS del parametro RequestOptions o a meno che non venga rilevato un errore.
È possibile inoltrare una richiesta di controllo del dispositivo interno non standard 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 possibilmente uno spazio di contesto.
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 Request di WdfIoTargetSendInternalIoctlOthersSynchronously.
-
Usare le informazioni sul contesto della richiesta ricevuta per i parametri WdfIoTargetSendInternalIoctlOthersSynchronously del metodo OtherArg1,OtherArg2 e OtherArg4.
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:
-
Specificare un handle di richiesta NULL per il parametro Request del metodo WdfIoTargetSendInternalIoctlOthersSynchronously, oppure creare un nuovo oggetto request e fornire il relativo handle:
- Se si specifica un handle di richiesta NULL , il framework usa un oggetto request 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 all'evtDriverDevice del driverAggiungi la funzione di callback per preallocare gli oggetti di richiesta per un dispositivo. Inoltre, un altro thread driver può chiamare WdfRequestCancelSentRequest per annullare la richiesta, se necessario.
Il driver può specificare un parametroRequestOptions diverso da NULL, indipendentemente dal fatto che il driver fornisca un parametro non NULL o null Request. È possibile, ad esempio, usare il parametro RequestOptions per specificare un valore di timeout.
-
Fornire spazio di contesto per i parametri OtherArg1,OtherArg2 e OtherArg4, se la richiesta richiede uno spazio di contesto per il metodo WdfIoTargetSendInternalIoctlOthersSynchronosSynchronously.
Il driver può specificare questo spazio di contesto come buffer allocati in locale, come handle WDFMEMORY o come elenchi di descrittori di memoria (MDLs). È possibile usare il metodo più pratico.
Sono disponibili le tecniche seguenti per specificare lo spazio del buffer:
-
Fornire buffer locali.
Poiché WdfIoTargetSendInternalIoctlOthersSynchronously gestisce le richieste di I/O in modo sincrono, il driver può creare buffer di richiesta locali alla 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 handle WDFMEMORY.
Chiamare WdfMemoryCreate 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);
-
Specificare GLI MDL.
I driver possono ottenere mdls associati a una richiesta di I/O ricevuta chiamando WdfRequestRetrieveInputWdmMdl e WdfRequestRetrieveOutputWdmMdl.
-
Fornire buffer locali.
Per altre informazioni su WdfIoTargetSendInternalIoctlOthersSynchronously, 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
L'esempio di codice seguente inizializza una struttura IRB IEEE 1394, usa l'indirizzo della struttura per inizializzare una struttura WDF_MEMORY_DESCRIPTOR e quindi chiama WdfIoTargetSendInternalIoctlOthersSynchronously.
WDF_MEMORY_DESCRIPTOR descriptor;
IRB Irb;
Irb.FunctionNumber = REQUEST_ALLOCATE_ADDRESS_RANGE;
Irb.Flags = 0;
Irb.u.AllocateAddressRange.Mdl = pAsyncAddressData->pMdl;
Irb.u.AllocateAddressRange.fulFlags = fulFlags;
Irb.u.AllocateAddressRange.nLength = nLength;
Irb.u.AllocateAddressRange.MaxSegmentSize = MaxSegmentSize;
Irb.u.AllocateAddressRange.fulAccessType = fulAccessType;
Irb.u.AllocateAddressRange.fulNotificationOptions = fulNotificationOptions;
Irb.u.AllocateAddressRange.Callback = NULL;
Irb.u.AllocateAddressRange.Context = NULL;
Irb.u.AllocateAddressRange.Required1394Offset = *Required1394Offset;
Irb.u.AllocateAddressRange.FifoSListHead = NULL;
Irb.u.AllocateAddressRange.FifoSpinLock = NULL;
Irb.u.AllocateAddressRange.AddressesReturned = 0;
Irb.u.AllocateAddressRange.p1394AddressRange = pAsyncAddressData->AddressRange;
Irb.u.AllocateAddressRange.DeviceExtension = deviceExtension;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&descriptor,
&Irb,
sizeof (IRB)
);
ntStatus = WdfIoTargetSendInternalIoctlOthersSynchronously(
IoTarget,
NULL,
IOCTL_1394_CLASS,
&descriptor,
NULL,
NULL,
NULL,
NULL
);
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 | PASSIVE_LEVEL |
Regole di conformità DDI | DeferredRequestCompleted(kmdf), DriverCreate(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf), WriteReqs(kmdf) |
Vedi anche
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER
WdfIoTargetFormatRequestForInternalIoctlOthers
WdfRequestCompleteWithInformation
Commenti e suggerimenti
https://aka.ms/ContentUserFeedback.
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedereInvia e visualizza il feedback per