Fonction IoGetDeviceObjectPointer (wdm.h)

La routine IoGetDeviceObjectPointer retourne un pointeur vers l’objet supérieur dans la pile de l’objet d’appareil nommé et un pointeur vers l’objet 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é. DesiredAccess est généralement 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 file 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 retournée

IoGetDeviceObjectPointer retourne STATUS_SUCCESS si elle réussit. Les valeurs de retour d’erreur possibles incluent les codes status 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 obligatoire vers IoCallDriver.

Cette routine retourne également un pointeur vers l’objet fichier correspondant. Lors du déchargement, un pilote peut déréférencer l’objet file comme un moyen de déréférencement indirect de l’objet d’appareil. Pour ce faire, le pilote appelle ObDereferenceObject à partir de sa routine Unload, en passant le pointeur d’objet fichier retourné par IoGetDeviceObjectPointer. Le fait de ne pas déréférencer l’objet de périphérique dans la routine de déchargement d’un pilote empêche le déchargement du pilote inférieur suivant. Toutefois, les pilotes qui ferment l’objet fichier avant le processus de déchargement doivent supprimer une référence supplémentaire sur l’objet d’appareil avant de déréférencer l’objet fichier. Sinon, la déréférencement de l’objet file peut entraîner une suppression prématurée de l’objet d’appareil.

Pour obtenir un pointeur vers le pilote de niveau le plus élevé 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 des périphériques de stockage. Pour s’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 qu’un 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 de périphérique sur celui de l’objet de périphérique du pilote de niveau inférieur suivant plus un.

Les appelants d’IoGetDeviceObjectPointer doivent s’exécuter sur IRQL = PASSIVE_LEVEL.

Configuration requise

Voir aussi

ACCESS_MASK

DEVICE_OBJECT

IoAllocateIrp

IoAttachDevice

IoAttachDeviceToDeviceStack

IoCallDriver

ObDereferenceObject

ObReferenceObjectByPointer