Funzione WdfIoTargetSendInternalIoctlSynchronously (wdfiotarget.h)
[Si applica solo a KMDF]
Il metodo WdfIoTargetSendInternalIoctlSynchronously compila una richiesta di controllo del dispositivo interno e la invia in modo sincrono a una destinazione di I/O.
Sintassi
NTSTATUS WdfIoTargetSendInternalIoctlSynchronously(
[in] WDFIOTARGET IoTarget,
[in, optional] WDFREQUEST Request,
[in] ULONG IoctlCode,
[in, optional] PWDF_MEMORY_DESCRIPTOR InputBuffer,
[in, optional] PWDF_MEMORY_DESCRIPTOR OutputBuffer,
[in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
[out, optional] PULONG_PTR BytesReturned
);
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, optional] Request
Handle per un oggetto richiesta del 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 di I/O.
[in, optional] InputBuffer
Puntatore a una struttura WDF_MEMORY_DESCRIPTOR allocata dal chiamante che descrive un buffer che verrà scritto nella destinazione di I/O. Per ulteriori informazioni, vedere la sezione Osservazioni successiva. Questo parametro è facoltativo e può essere NULL se la richiesta non invia dati.
[in, optional] OutputBuffer
Puntatore a una struttura di WDF_MEMORY_DESCRIPTOR allocata dal chiamante che descrive un buffer che riceverà dati dalla destinazione di I/O. Per ulteriori informazioni, vedere la sezione Osservazioni successiva. Questo parametro è facoltativo e può essere NULL se la richiesta non riceve dati.
[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) forniti da un altro driver al termine della richiesta chiamando WdfRequestCompleteWithInformation. Questo puntatore è facoltativo e può essere NULL.
Valore restituito
Se l'operazione ha esito positivo, WdfIoTargetSendInternalIoctlSynchronously 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. |
|
Dimensione della struttura WDF_REQUEST_SEND_OPTIONS a cui punta il parametro RequestOptions non è corretto. |
|
La richiesta è già stata accodata a una destinazione di I/O. |
|
Il framework non è riuscito ad allocare 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 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
Usare il metodo WdfIoTargetSendInternalIoctlSynchronously per inviare in modo sincrono le richieste di controllo del dispositivo interno. Per inviare richieste di controllo del dispositivo interno in modo asincrono, usare il metodo WdfIoTargetFormatRequestForInternalIoctl , seguito dal metodo WdfRequestSend .
Per altre informazioni sulle richieste di controllo dei dispositivi interne, vedere Uso dei codici di controllo di I/O.
Il metodo WdfIoTargetSendInternalIoctlSynchronously non restituisce fino al completamento della richiesta, a meno che il driver non fornisca un valore di timeout nella struttura di WDF_REQUEST_SEND_OPTIONS del parametro RequestOptions o a meno che non venga rilevato un errore.
È 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 richiesta e uno spazio buffer.
Per inoltrare una richiesta di controllo del dispositivo interna ricevuta dal driver in una coda di I/O:
- Specificare l'handle della richiesta ricevuta per il parametro Request del metodo Request WdfIoTargetSendInternalIoctlSynchronously.
-
Usare il buffer di input della richiesta ricevuta per il parametro InputBuffer del metodo WdfIoTargetSendInternalIoctlSynchronously.
Il driver deve chiamare WdfRequestRetrieveInputMemory per ottenere un handle per il buffer di input della richiesta. Il driver deve quindi inserire tale handle nella struttura WDF_MEMORY_DESCRIPTOR fornita dal driver per il parametro InputBuffer .
-
Usare il buffer di output della richiesta ricevuta per il parametro OutputBuffer del metodo WdfIoTargetSendInternalIoctlSynchronously.
Il driver deve chiamare WdfRequestRetrieveOutputMemory per ottenere un handle per il buffer di output della richiesta e deve quindi posizionare tale handle nella struttura WDF_MEMORY_DESCRIPTOR fornita dal driver per il parametro 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:
-
Fornire un handle di richiesta NULL per il parametro Request del metodo Request di WdfIoTargetSendInternalIoctlSynchronously oppure creare un nuovo oggetto richiesta e fornire il relativo handle:
- Se si specifica un handle di richiesta NULL , il framework usa un oggetto richiesta interno. Questa tecnica è semplice da usare, ma il driver non può annullare la richiesta.
- Se chiami WdfRequestCreate per creare uno o più oggetti richiesta, puoi riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. Questa tecnica consente alla funzione di callback EvtDriverDeviceAdd del driver di preallocare gli oggetti richiesta per un dispositivo. Inoltre, un altro thread del driver può chiamare WdfRequestCancelSentRequest per annullare la richiesta, se necessario.
Il driver può specificare un parametro RequestOptions diverso da NULL, indipendentemente dal fatto che il driver fornisca un parametro non NULL o nullRequest. È ad esempio possibile usare il parametro RequestOptions per specificare un valore di timeout.
-
Fornire spazio buffer per i parametri InputBuffer e OutputBuffer del metodo WdfIoTargetSendInternalIoctlSynchronously, se la richiesta li richiede.
Il driver può specificare questo spazio buffer come buffer allocati localmente, come handle WDFMEMORY o come elenchi di descrittori di memoria (MDLs). È possibile usare qualsiasi metodo sia più pratico.
Se necessario, il framework converte le descrizioni del buffer in modo che siano corrette per il tipo di trasferimento IOCTL. Per altre informazioni sui tipi di trasferimento IOCTL, vedere Definizione dei codici di controllo I/O.
Sono disponibili le tecniche seguenti per specificare lo spazio buffer:
-
Fornire buffer locali.
Poiché WdfIoTargetSendInternalIoctlSynchronously gestisce in modo sincrono le richieste di I/O, il driver può creare buffer di richiesta locali per la 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);
In alternativa, il driver può chiamare WdfRequestRetrieveInputMemory o WdfRequestRetrieveOutputMemory per ottenere un handle a un oggetto memoria framework che rappresenta il buffer della richiesta di I/O ricevuta, se si vuole che il driver passi il contenuto del buffer alla destinazione di I/O. Il driver non deve completare la richiesta di I/O ricevuta fino a quando la nuova richiesta inviata da WdfIoTargetSendInternalIoctlSynchronously alla destinazione di I/O è stata eliminata, riutilizzata o riformattata. WdfIoTargetSendInternalIoctlSynchronously 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.
-
Specificare mdls.
I driver possono ottenere mdls associati a una richiesta di I/O ricevuta chiamando WdfRequestRetrieveInputWdmMdl e WdfRequestRetrieveOutputWdmMdl.
-
Fornire buffer locali.
Per altre informazioni su WdfIoTargetSendInternalIoctlSynchronously, 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 definisce un buffer locale, inizializza una struttura WDF_MEMORY_DESCRIPTOR e chiama WdfIoTargetSendInternalIoctlSynchronously. In questo esempio viene specificato NULL per l'handle dell'oggetto richiesta, pertanto il framework creerà un nuovo oggetto richiesta per la destinazione di I/O.
WDF_MEMORY_DESCRIPTOR outputDescriptor;
NTSTATUS status;
MY_DRIVER_INFORMATION driverInformation;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
&outputDescriptor,
(PVOID) &driverInformation,
sizeof(MY_DRIVER_INFORMATION)
);
status = WdfIoTargetSendInternalIoctlSynchronously(
hidTarget,
NULL,
IOCTL_INTERNAL_GET_MY_DRIVER_INFORMATION,
NULL,
&outputDescriptor,
NULL,
NULL
);
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 | 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
WdfIoTargetFormatRequestForInternalIoctl
WdfIoTargetSendIoctlSynchronously
WdfRequestCompleteWithInformation
WdfRequestRetrieveOutputMemory
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