Fonction IoBuildSynchronousFsdRequest (wdm.h)
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) |