WdfIoTargetFormatRequestForWrite, fonction (wdfiotarget.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfIoTargetFormatRequestForWrite génère une demande d’écriture pour une cible d’E/S, mais n’envoie pas la requête.

Syntaxe

NTSTATUS WdfIoTargetFormatRequestForWrite(
  [in]           WDFIOTARGET       IoTarget,
  [in]           WDFREQUEST        Request,
  [in, optional] WDFMEMORY         InputBuffer,
  [in, optional] PWDFMEMORY_OFFSET InputBufferOffset,
  [in, optional] PLONGLONG         DeviceOffset
);

Paramètres

[in] IoTarget

Handle vers un objet cible d’E/S local ou distant qui a été obtenu à partir d’un appel précédent à WdfDeviceGetIoTarget ou WdfIoTargetCreate, ou à partir d’une méthode qu’une cible d’E/S spécialisée fournit.

[in] Request

Handle d’un objet de requête d’infrastructure. Pour plus d'informations, consultez la section Notes qui suit.

[in, optional] InputBuffer

Handle d’un objet de mémoire framework. Cet objet représente une mémoire tampon qui contient des données qui seront envoyées à la cible d’E/S. Ce paramètre est facultatif et peut être NULL. Pour plus d’informations sur ce paramètre, consultez la section Remarques suivante.

[in, optional] InputBufferOffset

Pointeur vers une structure de WDFMEMORY_OFFSET allouée à l’appelant qui fournit des valeurs facultatives de décalage d’octet et de longueur. L’infrastructure utilise ces valeurs pour déterminer l’adresse de début et la longueur, dans la mémoire tampon d’entrée, pour le transfert de données. Si ce pointeur a la valeur NULL, le transfert de données commence au début de la mémoire tampon d’entrée et la taille du transfert correspond à la taille de la mémoire tampon.

[in, optional] DeviceOffset

Pointeur vers un emplacement qui spécifie un décalage de départ pour le transfert. La cible d’E/S (c’est-à-dire le pilote inférieur suivant) définit comment utiliser cette valeur. Par exemple, les pilotes de la pile de pilotes d’un disque peuvent spécifier un décalage par rapport au début du disque. La cible d’E/S obtient ces informations dans le membre Parameters.Write.DeviceOffset de la structure WDF_REQUEST_PARAMETERS de la demande. Ce pointeur est facultatif. La plupart des pilotes définissent ce pointeur sur NULL.

Valeur retournée

WdfIoTargetFormatRequestForWrite retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INVALID_DEVICE_REQUEST	La longueur de transfert était supérieure à la longueur de la mémoire tampon, ou la demande d’E/S était déjà mise en file d’attente vers une cible d’E/S.
STATUS_INSUFFICIENT_RESOURCES	L’infrastructure n’a pas pu allouer de ressources système (généralement de la mémoire).
STATUS_REQUEST_NOT_ACCEPTED	Le paquet de demande d’E/S (IRP) que représente le paramètre Request 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.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Utilisez la méthode WdfIoTargetFormatRequestForWrite , suivie de la méthode WdfRequestSend , pour envoyer des demandes d’écriture de manière synchrone ou asynchrone. Vous pouvez également utiliser la méthode WdfIoTargetSendWriteSynchronously pour envoyer des demandes d’écriture de manière synchrone.

Vous pouvez transférer une demande d’E/S que votre pilote a reçue 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 de mémoire tampon.

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

Spécifiez le handle de la requête reçue pour le paramètre Request de la méthode WdfIoTargetFormatRequestForWrite.
Utilisez la mémoire tampon d’entrée de la demande reçue pour le paramètre InputBuffer de la méthode WdfIoTargetFormatRequestForWrite.
Le pilote doit appeler WdfRequestRetrieveInputMemory pour obtenir un handle sur un objet de mémoire framework qui représente la mémoire tampon d’entrée de la requête et doit utiliser ce handle comme valeur pour InputBuffer.

Pour plus d’informations sur le transfert d’une demande d’E/S, consultez Transfert de demandes d’E/S.

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 en créer de nouvelles.

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

Créez un objet de requête et fournissez son handle pour le paramètre Request de la méthode WdfIoTargetFormatRequestForWrite.
Appelez WdfRequestCreate pour préallouer un ou plusieurs objets de requête. Vous pouvez réutiliser ces objets de requête en appelant WdfRequestReuse. La fonction de rappel EvtDriverDeviceAdd de votre pilote peut préallouer des objets de requête pour un appareil.
Fournissez de l’espace tampon et fournissez le handle de la mémoire tampon pour le paramètre InputBuffer de la méthode WdfIoTargetFormatRequestForWrite.
Votre pilote doit spécifier cet espace tampon en tant que handle WDFMEMORY pour la mémoire gérée par l’infrastructure. Votre pilote peut effectuer l’une des opérations suivantes :
- Appelez WdfMemoryCreate ou WdfMemoryCreatePreallocated pour créer une mémoire tampon, si vous souhaitez que le pilote passe une nouvelle mémoire tampon à la cible d’E/S.
- Appelez WdfRequestRetrieveInputMemory pour obtenir un handle à l’objet mémoire qui représente la mémoire tampon d’une demande d’E/S reçue, si vous souhaitez que le pilote transmette le contenu de cette mémoire tampon à la cible d’E/S.
Notez que si votre pilote appelle WdfRequestRetrieveInputMemory et passe le handle de mémoire à WdfIoTargetFormatRequestForWrite, le pilote ne doit pas terminer la demande d’E/S reçue tant que le pilote n’a pas supprimé, réutilisé ou reformaté le nouvel objet de requête créé par le pilote. (WdfIoTargetFormatRequestForWrite incrémente le nombre de références de l’objet mémoire. La suppression, la réutilisation ou le reformatage d’un objet de requête décrémente le nombre de références de l’objet mémoire.)

Certaines cibles d’E/S acceptent les demandes d’écriture qui ont une mémoire tampon de longueur nulle. Pour ces cibles d’E/S, votre pilote peut spécifier NULL pour le paramètre InputBuffer .

Une fois qu’un pilote a appelé WdfIoTargetFormatRequestForWrite pour mettre en forme une requête d’E/S, il doit appeler WdfRequestSend pour envoyer la requête (de manière synchrone ou asynchrone) à une cible d’E/S.

Les appels multiples à WdfIoTargetFormatRequestForWrite qui utilisent la même requête ne provoquent pas d’allocations de ressources supplémentaires. Par conséquent, pour réduire le risque que WdfRequestCreate retourne STATUS_INSUFFICIENT_RESOURCES, la fonction de rappel EvtDriverDeviceAdd de votre pilote peut appeler WdfRequestCreate pour préallouer un ou plusieurs objets de requête pour un appareil. Le pilote peut ensuite réutiliser (appeler WdfRequestReuse), reformater (appeler WdfIoTargetFormatRequestForWrite) et renvoyer (appeler WdfRequestSend) chaque objet de requête sans risquer une STATUS_INSUFFICIENT_RESOURCES valeur de retour à partir d’un appel ultérieur à WdfRequestCreate. Tous les appels suivants à WdfIoTargetFormatRequestForWrite pour l’objet de requête réutilisé retournent STATUS_SUCCESS, si les valeurs de paramètre ne changent pas. (Si le pilote n’appelle pas la même méthode de mise en forme des requêtes à chaque fois, des ressources supplémentaires peuvent être allouées.)

Pour plus d’informations sur l’obtention d’informations status après la fin d’une demande d’E/S, consultez Obtention des informations d’achèvement.

Pour plus d’informations sur WdfIoTargetFormatRequestForWrite, consultez Envoi de demandes d’E/S à des cibles d’E/S générales.

Pour plus d’informations sur les cibles d’E/S, consultez Utilisation des cibles d’E/S.

Exemples

L’exemple de code suivant crée un objet de mémoire framework pour la mémoire tampon d’entrée d’une demande d’écriture, met en forme la demande d’écriture, inscrit une fonction de rappel CompletionRoutine et envoie la demande d’écriture à une cible d’E/S.

WDFREQUEST  request;
NTSTATUS  status;
WDFMEMORY  memory;
WDF_OBJECT_ATTRIBUTES  attributes;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         DRIVER_TAG,
                         WRITE_BUF_SIZE,
                         &memory,
                         NULL
                         );

if (!NT_SUCCESS(status)) {
    return status;
}

status = WdfIoTargetFormatRequestForWrite(
                                          IoTarget,
                                          request,
                                          memory,
                                          NULL,
                                          NULL
                                          );
if (!NT_SUCCESS(status)) {
        return status;
}
WdfRequestSetCompletionRoutine(
                               request,
                               MyReadRequestCompletionRoutine,
                               targetInfo
                               );
if (WdfRequestSend(
                   request,
                   IoTarget,
                   WDF_NO_SEND_OPTIONS
                   ) == FALSE) {
        status = WdfRequestGetStatus(request);
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfiotarget.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), RequestFormattedValid(kmdf), RequestSendAndForgetNoFormatting(kmdf), RequestSendAndForgetNoFormatting2(kmdf)