Funzione WdfUsbTargetPipeSendUrbSynchronously (wdfusb.h)

Articolo
07/16/2024

[Si applica solo a KMDF]

Il metodo WdfUsbTargetPipeSendUrbSynchronously compila una richiesta USB per una pipe USB specificata, usando i parametri di richiesta descritti da un specificato.

Sintassi

NTSTATUS WdfUsbTargetPipeSendUrbSynchronously(
  [in]           WDFUSBPIPE                Pipe,
  [in, optional] WDFREQUEST                Request,
  [in, optional] PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in]           PURB                      Urb
);

Parametri

[in] Pipe

Handle per un oggetto pipe del framework ottenuto chiamando WdfUsbInterfaceGetConfiguredPipe.

[in, optional] Request

Handle per un oggetto richiesta framework. Questo parametro è facoltativo e può essere NULL. Per altre informazioni, vedere la sezione Osservazioni seguente.

[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 altre informazioni, vedere la sezione Osservazioni seguente.

[in] Urb

Puntatore a una struttura DRIVER.

Se il driver precedentemente chiamato WdfUsbTargetDeviceCreateWithParameters per creare UsbDevice, il driver deve usare WdfUsbTargetDeviceCreateUrb o WdfUsbTargetDeviceCreateIsochUrb per creare questo comando.

Valore restituito

WdfUsbTargetPipeSendUrbSynchronously restituisce il valore di stato di completamento della destinazione I/O se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INFO_LENGTH_MISMATCH	La dimensione della struttura WDF_REQUEST_SEND_OPTIONS specificata dal parametro RequestOptions non è corretta.
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente disponibile.
STATUS_INVALID_DEVICE_REQUEST	IrQL del chiamante non è stato PASSIVE_LEVEL oppure la richiesta di I/O specificata è già stata accodata a una destinazione di I/O.
STATUS_IO_TIMEOUT	Il driver ha fornito un valore di timeout e la richiesta non è stata completata entro il tempo assegnato.
STATUS_REQUEST_NOT_ACCEPTED	Il pacchetto di richiesta di I/O (IRP) rappresentato dal parametro richiesta 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.

Osservazioni

Usare il metodo WdfUsbTargetPipeSendUrbSynchronously per inviare una richiesta USB in modo sincrono. Per inviare tali richieste in modo asincrono, usare WdfUsbTargetPipeFormatRequestForUrb, seguito da WdfRequestSend.

Il metodo WdfUsbTargetPipeSendUrbSynchronously non restituisce fino al completamento della richiesta, a meno che il driver non fornisca un valore di timeout nella struttura WDF_REQUEST_SEND_OPTIONS a cui punta il parametro RequestOptions o a meno che non venga rilevato un errore.

Il framework non esamina la richiesta USB. Se la richiesta modifica lo stato della pipe USB, il framework non sarà a conoscenza della modifica.

È possibile inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O oppure creare e inviare una nuova richiesta.

Per inoltrare una richiesta di I/O ricevuta dal driver in una coda di I/O, specificare l'handle della richiesta ricevuta per il parametro WdfUsbTargetPipeSendUrbSynchronously metodo Request.

Per creare e inviare una nuova richiesta, specificare un handle di richiesta NULL per il parametro request oppure creare un nuovo oggetto richiesta e specificarne l'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 si chiama WdfRequestCreate per creare uno o più oggetti richiesta, è possibile riutilizzare questi oggetti richiesta chiamando WdfRequestReuse. Questa tecnica consente al driver di EvtDriverDeviceAdd funzione di callback per 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 nullNULLnull, indipendentemente dal fatto che il driver fornisca un NULL nono un parametro RequestNULL . È ad esempio possibile usare il parametro RequestOptions per specificare un valore di timeout.

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 sul metodo WdfUsbTargetPipeSendUrbSynchronously e sulle destinazioni I/O USB, vedere Destinazioni I/O USB.

Esempi

Nell'esempio di codice riportato di seguito viene inizializzato UN VALORE DI CLASSE e viene inviato l'ISTRUZIONE ALLA pipe USB.

URB  urb;
PURB  pUrb = NULL;
NTSTATUS status;

pUrb = &urb;
pUrb->UrbHeader.Length = (USHORT) sizeof(struct _URB_GET_CURRENT_FRAME_NUMBER);
pUrb->UrbHeader.Function = URB_FUNCTION_GET_CURRENT_FRAME_NUMBER;
pUrb->UrbGetCurrentFrameNumber.FrameNumber = 0; 

status = WdfUsbTargetPipeSendUrbSynchronously(
                                              Pipe,
                                              Request,
                                              NULL,
                                              pUrb
                                              );

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
intestazione	wdfusb.h (include Wdfusb.h)
libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	PASSIVE_LEVEL
regole di conformità DDI	DriverCreate(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), SyncReqSend(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Vedere anche

WDF_REQUEST_SEND_OPTIONS

WdfRequestCancelSentRequest

WdfUsbInterfaceGetConfiguredPipe

Condividi tramite