A mounting point is a name that can be used to access a volume. When the filesystem driver mounts a volume, it must make that volume accessible by creating one or more mounting points for it.
Mounting points can be global (visible in all user sessions) or local (visible only to a specific user session). The add_mounting_point method creates global mounting points by default; applications must include the STGMP_LOCAL flag in the Flags parameter value to create local mounting points. (Note: The STGMP_MOUNT_MANAGER flag is not compatible with the STGMP_LOCAL flag.)
When creating a local mounting point, applications can specify a specific user session for it to be visible in by passing that session's Authentication ID for the AuthenticationId parameter (retrieval of Authentication IDs is discussed in a later section). If no Authentication ID is provided (i.e., 0 is passed), the local mounting point is created in the current user session; and if the application does this while running with elevated rights, then the local mounting point will only be visible in the elevated session, and consequently won't be available to applications in other sessions (such as, e.g., Windows Explorer).
When mounting points are added or removed, a system message is broadcast (WM_DEVICECHANGE) instructing Windows Explorer to refresh the list of drives available. However, these messages cannot cross user session boundaries; so if, for example, the application is running as a service, Windows Explorer may not receive the broadcast and thus fail to refresh the list of drives. To address this issue, CBFS Connect includes a Helper DLL which, among other things, helps ensure that Windows Explorer always refreshes the list of drives regardless of which user session the application is running in; please refer to that topic for more information.
Types of Mounting Points
There are a handful of different mounting point types, each of which exposes volumes in a slightly different manner:
- Drive letter mounting points
- UNC path mounting points
- Network mounting points
- Folder mounting points
Each type of mounting point is discussed in more detail below.
Drive Letter Mounting Points
Drive letter mounting points are one of the more commonly-used mounting point types thanks to users' familiarity with them. To create a drive letter mounting point, pass a string composed of a single character in the A-Z range followed by a colon (e.g., Z:) for the add_mounting_point method's MountingPoint parameter.
If the value passed for the add_mounting_point method's Flags parameter includes the STGMP_AUTOCREATE_DRIVE_LETTER flag, the class will assign a drive letter automatically. In this case, the value passed for the MountingPoint parameter must not include a drive letter.
UNC Path Mounting Points
UNC path mounting points make a volume available via a specific name, and unlike other mounting points types, they are not displayed anywhere in Windows Explorer; the UNC path must already be known.
UNC path mounting points consist of the \\.\ prefix, followed by a name (e.g., \\.\CBDrive1). The mounting-point-related class methods expect just the name (i.e., the UNC path with the \\.\ prefix omitted). So to add a new UNC path mounting point like, e.g., \\.\CBDrive1, call the add_mounting_point method and pass CBDrive1 for the MountingPoint parameter.
Network Mounting Points
Network mounting points are similar to other mounting point types, except that the system treats them as "remote devices". This distinction is useful since:
- Windows Explorer makes fewer requests for files located on remote devices.
- Some applications are more tolerant of timeouts and delays when working with remote devices.
Therefore, when an application is designed to work with some slow or remote storage medium, it's recommended that it use a network mounting point. When using network mounting points, it's important that the Helper DLL be used so that Windows Explorer displays the correct drive status.
To create a network mounting point using the add_mounting_point method, include the STGMP_NETWORK flag in the Flags parameter, and pass a string of the form <Local Name>;<Server Name>;<Share Name> for the MountingPoint parameter.
- <Local Name> is the name to use for the mounting point on the local system; it can be a drive letter or a name for use in a UNC path. Alternatively, it can be left empty, in which case the volume will only be accessible via the network path (see below) or the drive letter will be assigned automatically if the STGMP_AUTOCREATE_DRIVE_LETTER flag is used.
- Note: This "local name" is not related to the concept of "local and global mounting points" discussed in the overview.
- <Server Name> and <Share Name> are used to create a network path of the form \\<Server Name>\<Share Name>. This network path is not shared by default (see notes following examples below).
With the above information in mind, here are some examples of valid MountingPoint parameter values when creating network mounting points:
- Y:;MyServer;VirtualShare: Creates a network mounting point accessible both via the drive letter Y: and via the network path \\MyServer\VirtualShare.
- MyMountingPoint;MyServer;VirtualShare: Creates a network mounting point accessible both via the UNC path \\.\MyMountingPoint and via the network path \\MyServer\VirtualShare
- ;MyServer;VirtualShare: Creates a network mounting point accessible only via the network path \\MyServer\VirtualShare.
As stated above, the network paths created for network mounting points are not shared (i.e., visible to other computers on the network) by default. To have the class create an actual network share when add_mounting_point is called, applications must include either the STGMP_NETWORK_READ_ACCESS or the STGMP_NETWORK_WRITE_ACCESS flag in the Flags parameter value, and use empty string for the <Server Name> segment of the MountingPoint parameter value (the local computer's name is used). Note that when the mounting point is shared in this way, a local resource is created and then shared. The name of the resource is derived from the Share Name defined above. However, the set of allowed characters for such name is not strictly defined. Additionally, sharing is done using a call to NetShareAdd Windows API function, which can be called by Administrators, System Operators, and Power Users.
Folder Mounting Points
A folder mounting point makes a volume accessible through a folder located on another (pre-existing) NTFS volume. Folder mounting points are always visible to all users in the system, and their creation requires administrative privileges.
To create a folder mounting point using the add_mounting_point method, include the STGMP_MOUNT_MANAGER flag in the Flags parameter, and pass the target folder's absolute path for the MountingPoint parameter (e.g., C:\MountedDrives\MyMountingPoint). The target folder must already exist, must reside on an NTFS volume, and must be empty; otherwise, the call will fail.
An Authentication ID is a locally unique identifier (LUID) assigned to a logon session (or, "user session"), retrievable through the access token that represents said session. Applications can obtain the Authentication ID of a session from an access token or by enumerating logon sessions.
To obtain an Authentication ID from an access token, call the Windows API's GetTokenInformation function and pass either TokenGroupsAndPrivileges or TokenStatistics for the TokenInformation parameter. The resulting value will be a reference to a structure (TOKEN_GROUPS_AND_PRIVILEGES or TOKEN_STATISTICS, respectively) containing the needed Authentication ID.
To enumerate logon sessions, use the Windows API's LsaEnumerateLogonSessions function, which returns a list of existing logon session IDs (that is, Authentication IDs). To obtain additional information about a particular logon session (e.g., in order to determine if it's the desired one), use the Windows API's LsaGetLogonSessionData function.