Fonction IoBuildSynchronousFsdRequest (wdm.h)

Article
08/08/2023

La routine IoBuildSynchronousFsdRequest alloue et configure un IRP pour une demande d’E/S traitée de manière synchrone.

Syntaxe

__drv_aliasesMem PIRP IoBuildSynchronousFsdRequest(
  [in]           ULONG            MajorFunction,
  [in]           PDEVICE_OBJECT   DeviceObject,
  [in, out]      PVOID            Buffer,
  [in, optional] ULONG            Length,
  [in, optional] PLARGE_INTEGER   StartingOffset,
  [in]           PKEVENT          Event,
  [out]          PIO_STATUS_BLOCK IoStatusBlock
);

Paramètres

[in] MajorFunction

Code de fonction principal pour l’IRP. Ce code peut être IRP_MJ_PNP, IRP_MJ_READ, IRP_MJ_WRITE, IRP_MJ_FLUSH_BUFFERS ou IRP_MJ_SHUTDOWN.

[in] DeviceObject

Pointeur vers la structure DEVICE_OBJECT pour l’objet de périphérique du pilote inférieur suivant, qui représente l’appareil cible.

[in, out] Buffer

Pointeur vers une mémoire tampon de données. Si MajorFunction est IRP_MJ_WRITE, la mémoire tampon contient des données à écrire. Si MajorFunction est IRP_MJ_READ, la mémoire tampon reçoit des données. Si MajorFunction est IRP_MJ_FLUSH_BUFFERS ou IRP_MJ_SHUTDOWN, ce paramètre doit avoir la valeur NULL.

[in, optional] Length

Longueur, en octets, de la mémoire tampon pointée par Buffer. Pour les appareils tels que les disques, cette valeur doit être un multiple entier de la taille du secteur. À compter de Windows 8, la taille du secteur peut être de 4 096 ou 512 octets. Dans les versions antérieures de Windows, la taille du secteur est toujours de 512 octets. Ce paramètre est requis pour les demandes de lecture et d’écriture, mais doit être égal à zéro pour les demandes de vidage et d’arrêt.

[in, optional] StartingOffset

Pointeur vers le décalage sur le disque, pour les demandes de lecture et d’écriture. Les unités et la signification de cette valeur sont spécifiques au pilote. Ce paramètre est requis pour les demandes de lecture et d’écriture, mais doit être égal à zéro pour les demandes de vidage et d’arrêt.

[in] Event

Pointeur vers un objet d’événement initialisé et alloué par l’appelant. Le gestionnaire d’E/S définit l’événement à l’état Signaled lorsqu’un pilote de niveau inférieur termine l’opération demandée. Après avoir appelé IoCallDriver, le pilote peut attendre l’objet d’événement.

[out] IoStatusBlock

Pointeur vers un emplacement qui reçoit le bloc d’E/S status défini lorsque l’IRP est terminé par un pilote de niveau inférieur.

Valeur retournée

Si l’opération réussit, IoBuildSynchronousFsdRequest retourne un pointeur vers une structure IRP initialisée, avec l’emplacement de pile d’E/S du pilote inférieur suivant configuré à partir des paramètres fournis. Sinon, la routine retourne NULL.

Remarques

Un pilote de système de fichiers (FSD) ou un autre pilote de niveau supérieur peut appeler IoBuildSynchronousFsdRequest pour configurer les IRP qu’il envoie de manière synchrone à des pilotes de niveau inférieur.

IoBuildSynchronousFsdRequest alloue et configure un IRP qui demande aux pilotes de niveau inférieur d’effectuer une opération de lecture, d’écriture, de vidage ou d’arrêt synchrone. L’IRP contient suffisamment d’informations pour démarrer l’opération.

Les pilotes de niveau inférieur peuvent imposer des restrictions sur les paramètres fournis à cette routine. Par exemple, les pilotes de disque peuvent exiger que les valeurs fournies pour Length et StartingOffset soient des multiples entiers de la taille de secteur de l’appareil.

Après avoir appelé IoBuildSynchronousFsdRequest pour créer une requête, le pilote doit appeler IoCallDriver pour envoyer la demande au pilote inférieur suivant. Si IoCallDriver retourne STATUS_PENDING, le pilote doit attendre la fin de l’IRP en appelant KeWaitForSingleObject sur l’événement donné. La plupart des pilotes n’ont pas besoin de définir une routine IoCompletion pour l’IRP.

Les irPs créés par IoBuildSynchronousFsdRequest doivent être complétés par un appel de pilote à IoCompleteRequest. Un pilote qui appelle IoBuildSynchronousFsdRequest ne doit pas appeler IoFreeIrp, car le gestionnaire d’E/S libère ces IRP synchrones après l’appel d’IoCompleteRequest .

IoBuildSynchronousFsdRequest met en file d’attente les irPs qu’il crée dans une file d’attente IRP spécifique au thread actif. Si le thread se ferme, le gestionnaire d’E/S annule l’IRP.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible à partir de Windows 2000.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Règles de conformité DDI	ForwardedAtBadIrqlFsdSync(wdm), HwStorPortProhibitedDDDIs(storport),IoBuildSynchronousFsdRequestNoFree(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm)