ClusterGetVolumePathName function (resapi.h)

Article
10/13/2021

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

Retrieves the volume mount point on the cluster where the specified path is mounted.

Syntax

BOOL ClusterGetVolumePathName(
  [in]  LPCWSTR lpszFileName,
  [out] LPWSTR  lpszVolumePathName,
  [in]  DWORD   cchBufferLength
);

Parameters

[in] lpszFileName

A pointer to the input path string. Both absolute and relative file and directory names, for example "..", are acceptable in this path.

If you specify a relative directory or file name without a volume qualifier, ClusterGetVolumePathName returns the drive letter of the current volume.

If this parameter is an empty string, "", the function fails but the last error is set to ERROR_SUCCESS.

[out] lpszVolumePathName

A pointer to a string that receives the volume mount point for the input path.

[in] cchBufferLength

The length of the output buffer, in WCHARs.

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.

Remarks

The following examples may help. In these examples "Filename.Ext" does exist but "Path\that\does\not\exist" does not.

Input: "C:\ClusterStorage\Volume31\Filename.Ext"
Output: "C:\ClusterStorage\Volume31"
Input: "\\?\C:\ClusterStorage\Volume31\Filename.Ext"
Output: "\?\C:\ClusterStorage\Volume31"
Input: "C:\ClusterStorage\Volume31\Path\that\does\not\exist"
Output: "C:\ClusterStorage\Volume31"
Input: "\\?\Volume{deadbeef-895e-4a1d-9d64-9b82fa068d76}\ClusterStorage\Volume31\Filename.Ext"
Output: "\?\Volume{deadbeef-895e-4a1d-9d64-9b82fa068d76}\ClusterStorage\Volume31"
Input: "\\?\GLOBALROOT\Device\Harddisk0\Partition1\ClusterStorage\Volume31\Filename.Ext"
Output: "\?\GLOBALROOT\Device\Harddisk0\Partition1\ClusterStorage\Volume31"
Input: "\\?\GLOBALROOT\Device\HarddiskVolume1\ClusterStorage\Volume31\Filename.Ext"
Output: "\?\GLOBALROOT\Device\HarddiskVolume1\ClusterStorage\Volume31"

Windows Server 2008 R2: The initial release of ResApi.h containing the ClusterGetVolumePathName 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 ClusterGetVolumePathName 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