IOCTL_MOUNTMGR_CREATE_POINT IOCTL (mountmgr.h)

Article
03/01/2024

Les clients du gestionnaire de montage peuvent utiliser cet IOCTL pour demander au gestionnaire de montage de créer un nom de lien symbolique persistant pour le volume indiqué. Pour obtenir une présentation des différents types de liens symboliques persistants gérés par le gestionnaire de montage, consultez Prise en charge des demandes de gestionnaire de montage dans un pilote de classe de stockage.

L’entrée de cette demande est le nom du lien symbolique persistant à créer et un nom qui est déjà valide pour l’identification du volume. Le nom donné aux fins d’identification du volume peut être de n’importe quel type : un nom de volume unique, un nom de lien symbolique ou un nom d’appareil non persistant. Si le nouveau nom persistant n’est pas déjà utilisé, l’appel réussit et la base de données du gestionnaire de montage est modifiée pour refléter que le nouveau nom persistant appartient au volume. Si la base de données du gestionnaire de montage contient déjà le nouveau nom persistant, mais que le volume qui possède ce nom n’est pas dans le système, cet appel remplace la propriété du nom persistant donné.

Le gestionnaire de montage permet la création d’un nouveau nom de lien symbolique persistant même s’il n’a pas encore été averti du volume donné dans la notification de l’interface d’appareil MOUNTDEV_MOUNTED_DEVICE_GUID. Dans ce cas, le gestionnaire de montage crée simplement le lien symbolique et met à jour la base de données du gestionnaire de montage.

Le gestionnaire de montage applique une stratégie d’au plus une lettre de lecteur persistante par volume. Si une demande de IOCTL_MOUNTMGR_CREATE_POINT est envoyée avec une lettre de lecteur, la demande échoue si une lettre de lecteur est déjà affectée au volume, sauf si le gestionnaire de montage n’a pas encore été averti du volume par le biais de la notification de l’interface de l’appareil MOUNTDEV_MOUNTED_DEVICE_GUID. Dans ce dernier cas, l’appel réussit et le gestionnaire de montage vide la base de données du gestionnaire de montage de toutes les autres lettres de lecteur précédemment affectées au volume.

Si IOCTL_MOUNTMGR_CREATE_POINT spécifie une lettre de lecteur, la lettre de lecteur doit être en majuscules.

Notez qu’un client peut découvrir si le gestionnaire de montage a reçu la notification d’interface d’appareil MOUNTDEV_MOUNTED_DEVICE_GUID pour son volume en interrogeant le gestionnaire de montage avec IOCTL_MOUNTMGR_QUERY_POINTS.

Dans cet exemple de pseudocode, un client de gestionnaire de montage utilise IOCTL_MOUNTMGR_CREATE_POINT pour envoyer au gestionnaire de montage un nom d’objet d’appareil et son lien symbolique correspondant :

    // The persistent symbolic link is a drive letter in
    // this case:
    wsprintf(dosBuffer, L"\\DosDevices\\%C:", DriveLetter);
    RtlInitUnicodeString(&dosName, dosBuffer);
    // The nonpersistent volume (device) object name is
    // formed using the volume number as a suffix
    wsprintf(ntBuffer, L"\\Device\\HarddiskVolume%D", 
                       Extension->VolumeNumber);
    RtlInitUnicodeString(&ntName, ntBuffer);
    createPointSize = sizeof(MOUNTMGR_CREATE_POINT_INPUT) +
                      dosName.Length + ntName.Length;
    // Allocate a header with length and offset information
    createPoint = (PMOUNTMGR_CREATE_POINT_INPUT)
                  ExAllocatePool(PagedPool, 
                  createPointSize);
    createPoint->SymbolicLinkNameOffset = 
                  sizeof(MOUNTMGR_CREATE_POINT_INPUT);
    createPoint->SymbolicLinkNameLength = dosName.Length;
    createPoint->DeviceNameOffset = 
        createPoint -> SymbolicLinkNameOffset +
        createPoint -> SymbolicLinkNameLength;
    createPoint->DeviceNameLength = ntName.Length;
    RtlCopyMemory((PCHAR) createPoint + 
                  createPoint -> SymbolicLinkNameOffset,
                  dosName.Buffer, dosName.Length);
    RtlCopyMemory((PCHAR) createPoint + 
                  createPoint->DeviceNameOffset,
                  ntName.Buffer, ntName.Length);
    // Use the name of the mount manager device object
    // defined in mountmgr.h (MOUNTMGR_DEVICE_NAME) to
    // obtain a pointer to the mount manager.
    RtlInitUnicodeString(&name, MOUNTMGR_DEVICE_NAME);
    status = IoGetDeviceObjectPointer(&name,
                              FILE_READ_ATTRIBUTES, 
                              &fileObject, &deviceObject);
    KeInitializeEvent(&event, NotificationEvent, FALSE);
    irp = IoBuildDeviceIoControlRequest(
            IOCTL_MOUNTMGR_CREATE_POINT,
            deviceObject, createPoint, createPointSize, 
            NULL, 0, FALSE, &event, &ioStatus);
    // Send the irp to the mount manager requesting
    // that a new mount point (persistent symbolic link)
    // be created for the indicated volume.
    status = IoCallDriver(deviceObject, irp);

Code principal

IRP_MJ_DEVICE_CONTROL

Mémoire tampon d'entrée

Le gestionnaire de point de montage place un en-tête, défini en tant que structure MOUNTMGR_CREATE_POINT_INPUT dans Mountmgr.h, au début de la mémoire tampon dans Irp-AssociatedIrp.SystemBuffer>. Le gestionnaire de montage insère le nom du lien symbolique persistant nouvellement attribué à l’adresse indiquée par le membre SymbolicLinkNameOffset de cette structure, et il insère le nom de l’appareil non persistant à l’adresse indiquée par le membre DeviceNameOffset de cette structure.

Longueur de la mémoire tampon d’entrée

Parameters.DeviceIoControl.InputBufferLength dans l’emplacement de la pile d’E/S de l’IRP indique la taille, en octets, de la mémoire tampon d’entrée, qui doit être supérieure ou égale à sizeof(MOUNTMGR_CREATE_POINT_INPUT).

Mémoire tampon de sortie

None

Longueur de la mémoire tampon de sortie

None

Bloc d’état

Si l’opération réussit, le champ État est défini sur STATUS_SUCCESS.

Si InputBufferLength est inférieur à sizeof(MOUNTMGR_CREATE_POINT_INPUT), le champ Status est défini sur STATUS_INVALID_PARAMETER.

Configuration requise

Condition requise	Valeur
En-tête	mountmgr.h (include Mountmgr.h)

Voir aussi

MOUNTMGR_CREATE_POINT_INPUT

Partager via