Fonction IoBuildSynchronousFsdRequest (wdm.h)
La routine IoBuildSynchronousFsdRequest alloue et configure un IRP pour une requête 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_BUFFERSou IRP_MJ_SHUTDOWN.
[in] DeviceObject
Pointeur vers la structure DEVICE_OBJECT pour l’objet 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 être NULL.
[in, optional] Length
Longueur, en octets, de la mémoire tampon pointée par tampon. 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 alloué par l’appelant et initialisé. 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’état d’E/S défini lorsque l’IRP est terminé par un pilote de niveau inférieur.
Valeur de retour
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 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 fournisseurs d’intégration qu’il envoie de manière synchrone aux pilotes de niveau inférieur.
IoBuildSynchronousFsdRequest alloue et configure un IRP qui demande aux pilotes de niveau inférieur d’effectuer une opération synchrone de lecture, d’écriture, de vidage ou d’arrêt. 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 Longueur et StartingOffset être des multiples entiers de la taille du secteur de l’appareil.
Après avoir appelé IoBuildSynchronousFsdRequest pour créer une requête, le pilote doit appeler IoCallDriver pour envoyer la requête 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 dedonné. La plupart des pilotes n’ont pas besoin de définir une routine IoCompletion pour l’IRP.
Les adresses IP virtuelles créées par IoBuildSynchronousFsdRequest doivent être effectuées par l’appel d’un 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' IoCompleteRequest a été appelé.
IoBuildSynchronousFsdRequest met en file d’attente les runtimes d’intégration qu’il crée dans une file d’attente IRP spécifique au thread actuel. Si le thread se ferme, le gestionnaire d’E/S annule l’IRP.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible à partir de Windows 2000. |
| plateforme cible | Universel |
| d’en-tête | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
| règles de conformité DDI | ForwardedAtBadIrqlFsdSync(wdm), HwStorPortProhibitedDDIs(storport), IoBuildSynchronousFsdRequestNoFree(wdm), IoBuildSynchronou, IoBuildSynchronousFsdRequestWaitTimeout(wdm), PowerIrpDDis(wdm), SignalEventInCompletion(wdm) |