ClusterGetVolumeNameForVolumeMountPoint function (resapi.h)

Article
11/22/2022

[ClusterGetVolumeNameForVolumeMountPoint is available for use in the operating systems specified in the Requirements section. It may be altered or unavailable in subsequent versions. Instead, use GetVolumeNameForVolumeMountPoint.]

Retrieves a cluster volume GUID path for the volume that is associated with the specified cluster shared volume (CSV) mount point (drive letter, volume GUID path, or mounted folder).

Syntax

BOOL ClusterGetVolumeNameForVolumeMountPoint(
  [in]  LPCWSTR lpszVolumeMountPoint,
  [out] LPWSTR  lpszVolumeName,
  [in]  DWORD   cchBufferLength
);

Parameters

[in] lpszVolumeMountPoint

A pointer to a string that contains the path of a mounted folder (for example, "Y:\MountX") or a drive letter (for example, "X:\"). The string must end with a trailing backslash (\).

[out] lpszVolumeName

A pointer to a string that receives the volume GUID path. This path is of the form "\?\Volume{GUID}" where GUID is a GUID that identifies the volume. If there is more than one volume GUID path for the volume, only the first one in the mount manager's cache is returned. The string returned is in the format required for IVssBackupComponents::AddToSnapshotSet and IVssBackupComponents::IsVolumeSupported.

[in] cchBufferLength

The length of the output buffer, in WCHARs. A reasonable size for the buffer to accommodate the largest possible volume GUID path is 51 characters.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. If the input CSV is not locally mounted the call will fail with an ERROR_CSV_VOLUME_NOT_LOCAL (5951) error.

Remarks

The following examples may help. In these examples "Filename.Ext" does exist but "File\that\does\not\exist" and "Directory\that\does\not\exist" do not.

Input: "C:\ClusterStorage\Volume31\"
Output: "\?\Volume{deadbeef-895e-4a1d-9d64-9b82fa068d76}"
Input: "C:\ClusterStorage\Volume31\"
Output: Function fails and sets a last error of ERROR_CSV_VOLUME_NOT_LOCAL (5951).

Note The CSV volume specified for input is not locally mounted for direct I/O.
Input: "\\?\C:\ClusterStorage\Volume31\Filename.Ext"
Output: Function fails and sets a last error of ERROR_INVALID_PARAMETER (87).
Input: "C:\ClusterStorage\Volume31\File\that\does\not\exist"
Output: Function fails and sets a last error of ERROR_INVALID_NAME (123).
Input: "C:\ClusterStorage\Volume31\Directory\that\does\not\exist\"
Output: Function fails and sets a last error of ERROR_INVALID_NAME (123).
Input: "\\?\Volume{deadbeef-895e-4a1d-9d64-9b82fa068d76}\"
Output: "\?\Volume{deadbeef-895e-4a1d-9d64-9b82fa068d76}"
Input: "\\?\Volume{de8b99bb-895e-4a1d-9d64-9b82fa068d76}\ClusterStorage\Volume31\"
Output: "\?\Volume{deadbeef-895e-4a1d-9d64-9b82fa068d76}"

Note The volume in the output is a CSV and is different from the system volume that was part of the input.
Input: "\\?\GLOBALROOT\Device\Harddisk0\Partition1\ClusterStorage\Volume31\"
Output: "\?\Volume{deadbeef-895e-4a1d-9d64-9b82fa068d76}"
Input: "\\?\GLOBALROOT\Device\HarddiskVolume1\ClusterStorage\Volume31\"
Output: "\?\Volume{deadbeef-895e-4a1d-9d64-9b82fa068d76}"

Windows Server 2008 R2: The initial release of ResApi.h containing the ClusterGetVolumeNameForVolumeMountPoint function used TCHAR-based data types instead of WCHAR-based data types. The UNICODE preprocessor define must be set before ResApi.h is included.

#define UNICODE 1
#include <ResApi.h>

The ClusterGetVolumeNameForVolumeMountPoint function must be called from a node of the cluster.

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2008 R2 Enterprise, Windows Server 2008 R2 Datacenter
Target Platform	Windows
Header	resapi.h
Library	ResUtils.Lib
DLL	ResUtils.Dll