Fonction IoGetDeviceObjectPointer (wdm.h)
La routine IoGetDeviceObjectPointer retourne un pointeur vers l’objet supérieur dans la pile de l’objet appareil nommé et un pointeur vers l’objet de fichier correspondant, si l’accès demandé aux objets peut être accordé.
Syntaxe
NTSTATUS IoGetDeviceObjectPointer(
[in] PUNICODE_STRING ObjectName,
[in] ACCESS_MASK DesiredAccess,
[out] PFILE_OBJECT *FileObject,
[out] PDEVICE_OBJECT *DeviceObject
);
Paramètres
[in] ObjectName
Pointeur vers une mémoire tampon qui contient une chaîne Unicode qui est le nom de l’objet d’appareil.
[in] DesiredAccess
Spécifie la valeur ACCESS_MASK qui représente l’accès souhaité. En règle générale, DesiredAccess est FILE_READ_DATA. Rarement, les droits d’accès FILE_WRITE_DATA ou FILE_ALL_ACCESS sont spécifiés.
[out] FileObject
Pointeur vers l’objet de fichier qui représente l’objet d’appareil correspondant vers le code en mode utilisateur si l’appel réussit.
[out] DeviceObject
Pointeur vers l’objet d’appareil qui représente l’appareil logique, virtuel ou physique nommé si l’appel réussit.
Valeur de retour
IoGetDeviceObjectPointer retourne STATUS_SUCCESS si elle réussit. Les valeurs de retour d’erreur possibles incluent les codes d’état suivants :
STATUS_OBJECT_TYPE_MISMATCH
STATUS_INVALID_PARAMETER
STATUS_PRIVILEGE_NOT_HELD
STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_INVALID
Remarques
IoGetDeviceObjectPointer établit une « connexion » entre l’appelant et le pilote de niveau inférieur suivant. Un appelant réussi peut utiliser le pointeur d’objet d’appareil retourné pour initialiser ses propres objets d’appareil. Il peut également être utilisé comme argument pour IoAttachDeviceToDeviceStack, IoCallDriver, et toute routine qui crée des IRPs pour les pilotes inférieurs. Le pointeur retourné est un argument requis pour IoCallDriver .
Cette routine retourne également un pointeur vers l’objet de fichier correspondant. Lors du déchargement, un pilote peut déréférencer l’objet de fichier comme moyen de désréférencer indirectement l’objet d’appareil. Pour ce faire, le pilote appelle ObDereferenceObject à partir de sa routine Deload, en passant le pointeur d’objet de fichier retourné par IoGetDeviceObjectPointer. L’échec de la déréférencement de l’objet de périphérique dans la routine de déchargement d’un pilote empêche le pilote suivant d’être déchargé. Toutefois, les pilotes qui ferment l’objet de fichier avant le processus de déchargement doivent extraire une référence supplémentaire sur l’objet d’appareil avant de déreferencer l’objet de fichier. Sinon, la déréférencement de l’objet de fichier peut entraîner une suppression prématurée de l’objet d’appareil.
Pour obtenir un pointeur vers le pilote de niveau supérieur dans la pile des pilotes du système de fichiers, un pilote doit s’assurer que le système de fichiers est monté ; si ce n’est pas le cas, cette routine traverse la pile d’appareils de stockage. Pour vous assurer que le système de fichiers est monté sur le périphérique de stockage, le pilote doit spécifier un masque d’accès approprié, tel que FILE_READ_DATA ou FILE_WRITE_ATTRIBUTES, dans le paramètre DesiredAccess. La spécification de FILE_READ_ATTRIBUTES n’entraîne pas le montage du système de fichiers.
Une fois que tout pilote de niveau supérieur s’est chaîné sur un autre pilote en appelant correctement cette routine, le pilote de niveau supérieur doit définir le champ StackSize dans son objet d’appareil sur celui de l’objet périphérique du pilote de niveau inférieur suivant plus un.
Les appelants de IoGetDeviceObjectPointer doivent s’exécuter à IRQL = PASSIVE_LEVEL.
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 | PASSIVE_LEVEL |
| règles de conformité DDI | HwStorPortProhibitedDDIs(storport), IrqlIoPassive5(wdm), PowerIrpDDis(wdm) |