WdfUsbTargetPipeWriteSynchronously, fonction (wdfusb.h)

Article
07/16/2024

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetPipeWriteSynchronously génère une requête d’écriture et l’envoie de manière synchrone à un canal de sortie USB spécifié.

Syntaxe

NTSTATUS WdfUsbTargetPipeWriteSynchronously(
  [in]            WDFUSBPIPE                Pipe,
  [in, optional]  WDFREQUEST                Request,
  [in, optional]  PWDF_REQUEST_SEND_OPTIONS RequestOptions,
  [in, optional]  PWDF_MEMORY_DESCRIPTOR    MemoryDescriptor,
  [out, optional] PULONG                    BytesWritten
);

Paramètres

[in] Pipe

Handle vers un objet de canal d’infrastructure obtenu en appelant WdfUsbInterfaceGetConfiguredPipe.

[in, optional] Request

Handle vers un objet de requête de framework. Ce paramètre est facultatif et peut être NULL. Pour plus d’informations, consultez la section Remarques suivante.

[in, optional] RequestOptions

Pointeur vers une structure WDF_REQUEST_SEND_OPTIONS allouée par l’appelant qui spécifie les options de la requête. Ce pointeur est facultatif et peut être NULL. Pour plus d’informations, consultez la section Remarques suivante.

[in, optional] MemoryDescriptor

Pointeur vers une structure WDF_MEMORY_DESCRIPTOR allouée par l’appelant qui décrit la mémoire tampon qui contient des données écrites sur l’appareil. Pour plus d’informations sur cette mémoire tampon, consultez la section Remarques suivantes.

[out, optional] BytesWritten

Pointeur vers un emplacement qui reçoit le nombre d’octets écrits, si l’opération réussit. Ce paramètre est facultatif et peut être NULL.

Valeur de retour

WdfUsbTargetPipeWriteSynchronously retourne la valeur d’état d’achèvement de la cible d’E/S si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Retourner le code	Description
STATUS_INFO_LENGTH_MISMATCH	Taille de la structure WDF_REQUEST_SEND_OPTIONS à laquelle le paramètre RequestOptions pointait incorrect.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	Mémoire insuffisante disponible.
STATUS_INVALID_DEVICE_REQUEST	L’IRQL de l’appelant n’était pas PASSIVE_LEVEL, un descripteur de mémoire non valide a été spécifié, le type du canal n’était pas valide, le sens du transfert n’était pas valide ou la requête d’E/S spécifiée était déjà mise en file d’attente vers une cible d’E/S.
STATUS_IO_TIMEOUT	Le pilote a fourni une valeur de délai d’attente et la demande n’a pas terminé dans le délai imparti.
STATUS_REQUEST_NOT_ACCEPTED	Le paquet de requête d’E/S (IRP) que le paramètre Request représente ne fournit pas suffisamment de structures IO_STACK_LOCATION pour permettre au pilote de transférer la requête.

Cette méthode peut également retourner d’autres valeurs NTSTATUS .

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

Utilisez la méthode WdfUsbTargetPipeWriteSynchronously pour envoyer des demandes d’écriture de manière synchrone. Pour envoyer des requêtes d’écriture de manière asynchrone, utilisez WdfUsbTargetPipeFormatRequestForWrite, suivie de WdfRequestSend.

Le canal spécifié doit être un canal de sortie, et le type de du canal doit être WdfUsbPipeTypeBulk ou WdfUsbPipeTypeInterrupt.

La méthode WdfUsbTargetPipeWriteSynchronously ne retourne pas tant que la requête n’est pas terminée, sauf si le pilote fournit une valeur de délai d’attente dans la structure RequestOptions du paramètre WDF_REQUEST_SEND_OPTIONS, ou à moins qu’une erreur ne soit détectée.

Vous pouvez transférer une demande d’E/S reçue par votre pilote dans une file d’attente d’E/S, ou vous pouvez créer et envoyer une nouvelle demande. Dans les deux cas, l’infrastructure nécessite un objet de requête et un espace tampon.

Pour transférer une demande d’E/S reçue par votre pilote dans une file d’attente d’E/S :

Spécifiez le handle de la demande reçue pour le paramètre de demande de .
Utilisez la mémoire tampon d’entrée de la requête reçue pour le paramètre MemoryDescriptor.
Le pilote doit appeler WdfRequestRetrieveInputMemory pour obtenir un handle vers un objet mémoire du framework qui représente la mémoire tampon d’entrée de la requête, puis placer ce handle dans la structure WDF_MEMORY_DESCRIPTOR qui MemoryDescriptor pointe vers.

Pour plus d’informations sur le transfert d’une requête d’E/S, consultez demandes d’E/S de transfert.

Les pilotes divisent souvent les demandes d’E/S reçues en demandes plus petites qu’ils envoient à une cible d’E/S, afin que votre pilote puisse créer de nouvelles requêtes.

Pour créer une demande d’E/S :

Fournissez un handle de requête NULL
pour le paramètre WdfUsbTargetPipeWriteSynchronously méthode Request, ou créez un objet de requête et fournissez son handle :
- Si vous fournissez un handle de requête NULL , l’infrastructure utilise un objet de requête interne. Cette technique est simple à utiliser, mais le pilote ne peut pas annuler la demande.
- Si vous appelez WdfRequestCreate pour créer un ou plusieurs objets de requête, vous pouvez réutiliser ces objets de requête en appelant WdfRequestReuse. Cette technique permet aux EvtDriverDeviceAdd fonction de rappel de préallouer les objets de requête d’un appareil. En outre, un autre thread de pilote peut appeler WdfRequestCancelSentRequest pour annuler la requête, si nécessaire.
Votre pilote peut spécifier un paramètre RequestOptions nonNULL ou une NULLDemander paramètre. Vous pouvez, par exemple, utiliser le paramètre RequestOptions pour spécifier une valeur de délai d’attente.
Fournissez de l’espace tampon pour le paramètre MemoryDescriptor de la méthode WdfUsbTargetPipeWriteSynchronous ly.
Votre pilote peut spécifier cet espace de mémoire tampon en tant que mémoire tampon allouée localement, en tant que handle WDFMEMORY ou en tant que MDL. Vous pouvez utiliser la méthode la plus pratique.

Si nécessaire, l’infrastructure convertit la description de la mémoire tampon en une qui est correcte pour la méthode de de la cible d’E/S pour accéder aux mémoires tampons de données.

Les techniques suivantes sont disponibles :
- Fournir une mémoire tampon locale
  Étant donné que WdfUsbTargetPipeWriteSynchronously gère les requêtes d’E/S de manière synchrone, le pilote peut créer des mémoires tampons de requête locales à la routine appelante, comme l’illustre l’exemple de code suivant.
```
WDF_MEMORY_DESCRIPTOR  memoryDescriptor;
MY_BUFFER_TYPE  myBuffer;
WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(&memoryDescriptor,
                                  (PVOID) &myBuffer,
                                  sizeof(myBuffer));
```
- Fournir un handle WDFMEMORY
  Appelez WdfMemoryCreate ou WdfMemoryCreatePreallocated pour obtenir un handle de mémoire gérée par l’infrastructure, comme l’illustre l’exemple de code suivant.
```
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);
```
  Le pilote peut également appeler WdfRequestRetrieveInputMemory pour obtenir un handle vers un objet mémoire de framework qui représente la mémoire tampon d’entrée d’une demande d’E/S reçue, si vous souhaitez que le pilote passe le contenu de cette mémoire tampon à la cible d’E/S. Le pilote ne doit pas terminer la demande d’E/S reçue tant que la nouvelle requête WdfUsbTargetPipeWriteSynchronously envoyées à la cible d’E/S a été supprimée, réutilisée ou reformattée. (WdfUsbTargetPipeWriteSynchronously incrémente le nombre de références de l’objet mémoire. La suppression, la réutilisation ou la reformatage d’un objet de requête décrémente le nombre de références de l’objet mémoire.)
- Fournir un MDL
  Les pilotes peuvent obtenir le MDL associé à une demande d’E/S reçue en appelant WdfRequestRetrieveInputWdmMdl.

Pour plus d’informations sur l’obtention des informations d’état une fois qu’une demande d’E/S est terminée, consultez Obtention des informations d’achèvement.

Pour plus d’informations sur la méthode WdfUsbTargetPipeWriteSynchronously et les cibles d’E/S USB, consultez cibles d’E/S USB.

Exemples

L’exemple de code suivant crée un objet mémoire, obtient un pointeur vers la mémoire tampon de l’objet, remplit la mémoire tampon et utilise la mémoire tampon comme entrée pour WdfUsbTargetPipeWriteSynchronously.

WDF_MEMORY_DESCRIPTOR  writeBufDesc;
WDFMEMORY  wdfMemory;
ULONG  writeSize, bytesWritten;
size_t  bufferSize;
NTSTATUS status;

writeSize = SMALL_BUF_LEN;
status = WdfMemoryCreate(
                         WDF_NO_OBJECT_ATTRIBUTES,
                         NonPagedPool,
                         0,
                         writeSize,
                         &wdfMemory,
                         NULL
                         );
if (!NT_SUCCESS(status)){
    return status;
}

writeBuffer = WdfMemoryGetBuffer(
                                 wdfMemory,
                                 &bufferSize
                                 );

FillMyBuffer(
             writeBuffer,
             writeSize
             );

WDF_MEMORY_DESCRIPTOR_INIT_BUFFER(
                                  &writeBufDesc,
                                  writeBuffer,
                                  writeSize
                                  );

status = WdfUsbTargetPipeWriteSynchronously(
                                            pipeHandle,
                                            NULL,
                                            NULL,
                                            &writeBufDesc,
                                            &bytesWritten
                                            );

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’en-tête	wdfusb.h (include Wdfusb.h)
bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
règles de conformité DDI	DriverCreate(kmdf), InternalIoctlReqs(kmdf), IoctlReqs(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ReadReqs(kmdf), SyncReqSend(kmdf), usbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)