Funzione WdfIoTargetSendInternalIoctlOthersSynchronously (wdfiotarget.h)

Articolo
07/16/2024

[Si applica solo a KMDF]

Il metodo WdfIoTargetSendInternalIoctlOthersSynchronously compila una richiesta di controllo del dispositivo interno non standard e la 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 per un oggetto di destinazione I/O locale o remoto ottenuto da una chiamata precedente a WdfDeviceGetIoTarget o WdfIoTargetCreateo da un metodo fornito da una destinazione di I/O specializzata.

[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] IoctlCode

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

[in, optional] OtherArg1

Puntatore a una struttura WDF_MEMORY_DESCRIPTOR che descrive un buffer di memoria che contiene informazioni sul contesto. Questo parametro è facoltativo e può essere NULL.

[in, optional] OtherArg2

Puntatore a una struttura WDF_MEMORY_DESCRIPTOR che descrive un buffer di memoria che contiene informazioni sul contesto. Questo parametro è facoltativo e può essere NULL.

[in, optional] OtherArg4

Puntatore a una struttura WDF_MEMORY_DESCRIPTOR che descrive un buffer di memoria che contiene informazioni sul 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 altre informazioni, vedere la sezione Osservazioni seguente.

[out, optional] BytesReturned

Puntatore a una posizione che riceve informazioni (ad esempio il numero di byte trasferiti) forniti da un altro driver 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
STATUS_INVALID_PARAMETER	È stato rilevato un parametro non valido.
STATUS_INFO_LENGTH_MISMATCH	Dimensioni della struttura WDF_REQUEST_SEND_OPTIONS a cui punta il parametro RequestOptions non è corretto.
STATUS_INVALID_DEVICE_REQUEST	La richiesta è 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_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

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 che interagiscono, è possibile definire il modo in cui questo set di driver usa gli argomenti della richiesta: OtherArg1, OtherArg2e OtherArg4.

Non esiste alcun parametro chiamato OtherArg3 perché il framework associa questi parametri all'Argument1, Argument2e Argument4 membri dell'unione Other.Parameters nella struttura 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 dei dispositivi interne non standard in modo sincrono. Per inviare richieste di controllo dei dispositivi interne in modo asincrono, usare WdfIoTargetFormatRequestForInternalIoctlOthers, seguito da WdfRequestSend.

Per altre informazioni sulle richieste di controllo dei dispositivi interne, vedere Uso dei codici di controllo I/O.

Il metodo WdfIoTargetSendInternalIoctlOthersSynchronously non restituisce fino al completamento della richiesta, a meno che il driver non fornisca un valore di timeout nella struttura parametro WDF_REQUEST_SEND_OPTIONS 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 è possibile creare e inviare una nuova richiesta. In entrambi i casi, il framework richiede un oggetto richiesta ed eventualmente 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 internalIoctlOthersSynchronous ly.
Usare le informazioni di contesto della richiesta ricevuta per il metodo WdfIoTargetSendInternalIoctlOthersSynchronouslyOtherArg1,OtherArg2eAltriArg4 parametri.
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:

Specificare un handle di richiesta NULL
per il parametro Request WdfIoTargetSendInternalIoctlOthersSynchronously metodo 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.
Specificare lo spazio di contesto per il metodo WdfIoTargetSendInternalIoctlOthersSynchronouslyOtherArg1,OtherArg2e parametri OtherArg4, se la richiesta li richiede.
Il driver può specificare questo spazio di contesto come buffer allocati localmente, come handle WDFMEMORY o come elenchi di descrittori di memoria (MDLs). È possibile usare qualsiasi metodo sia più pratico.

Sono disponibili le tecniche seguenti per specificare lo spazio del buffer:
- Specificare buffer locali.
  Poiché WdfIoTargetSendInternalIoctlOthersSynchronously gestisce le richieste di I/O in modo sincrono, il driver può creare buffer delle richieste 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));
```
- Fornire handle WDFMEMORY.
  Chiamare WdfMemoryCreare 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);
```
- Fornire mdls.
  I driver possono ottenere mdls associati a una richiesta di I/O ricevuta chiamando WdfRequestRetrieveInputWdmMdl e WdfRequestRetrieveOutputWdmdl.

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 WdfIoTargetSendInternalIoctlOthersSynchronously, vedere l'invio di richieste di I/O a destinazioni I/O generali.

Per altre informazioni sulle destinazioni di I/O, vedere Uso delle destinazioni di I/O.

Esempi

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
                                                           );

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	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)