GetVolumePathNameW 函式 (fileapi.h)

擷取裝載指定路徑的磁碟區裝入點。

語法

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

參數

[in] lpszFileName

輸入路徑字串的指標。 絕對和相對檔案和目錄名稱，例如 “..” 在此路徑中都是可接受的。

如果您指定沒有磁碟區限定符的相對目錄或檔名， GetVolumePathName 會傳回開機磁碟區的驅動器號。

如果此參數是空字串 “”，則函式會失敗，但最後一個錯誤會設定為 ERROR_SUCCESS。

[out] lpszVolumePathName

接收輸入路徑之磁碟區裝入點之字串的指標。

[in] cchBufferLength

TCHAR 中輸出緩衝區的長度。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

如果傳遞指定的路徑， GetVolumePathName 會傳回磁碟區裝入點的路徑，這表示它會傳回指定路徑端點所在之磁碟區的根目錄。

例如，假設您已在上 C:\Mnt\Ddrive 掛接磁碟區 D，並在 掛接的 C:\Mnt\Ddrive\Mnt\Edrive磁碟區 E。 也假設您有路徑 為的 E:\Dir\Subdir\MyFile檔案。 如果您傳遞 C:\Mnt\Ddrive\Mnt\Edrive\Dir\Subdir\MyFile 至 GetVolumePathName，它會傳回路徑 C:\Mnt\Ddrive\Mnt\Edrive\。

如果相對目錄或檔案是在沒有磁碟區限定符的情況下傳遞，則函式會傳回開機磁碟區的驅動器號。 如果指定了無效的檔案或目錄名稱，但沒有有效的磁碟區限定符，也會傳回開機磁碟區的驅動器號。 如果指定有效的磁碟區規範，且磁碟區存在，但指定了無效的檔案或目錄名稱，則函式將會成功，而且將會傳回該磁碟區名稱。 如需範例，請參閱本主題的一節。

您必須指定有效的 Win32 命名空間路徑。 如果您指定 NT 命名空間路徑，例如 \DosDevices\H: 或 \Device\HardDiskVolume6，函式會傳回開機磁碟區的驅動器號，而不是該 NT 命名空間路徑的驅動器號。

如需路徑名稱和命名空間的詳細資訊，請參閱 命名檔案、路徑和命名空間。

您可以同時指定本機和遠端路徑。 如果您指定本機路徑， GetVolumePathName 會傳回完整路徑，其前置詞是代表磁碟區的最長前置詞。

如果指定網路共用， GetVolumePathName 會傳回 GetDriveType 傳回 DRIVE_REMOTE的最短路徑，這表示路徑會驗證為存在且目前使用者可以存取的遠端磁碟驅動器。

在某些情況下，不會傳回尾端反斜杠。 當輸出緩衝區長度太短時，就會發生這些情況。 例如，如果 lpszFileName 為 C: 且 lpszVolumePathName 長度為 4 個字符，則傳回的值為 ;不過，如果 lpszVolumePathName 長度為 3 個字符，則傳回C:\的值會是 C:。 設定傳回緩衝區大小的較安全但較慢方式是呼叫 GetFullPathName 函式，然後確定緩衝區大小至少與 GetFullPathName 傳回的完整路徑大小相同。 如果輸出緩衝區超過一個字元太短，函式將會失敗並傳回錯誤。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。

技術	支援
伺服器消息塊 (SMB) 3.0 通訊協定	No
SMB 3.0 透明故障轉移 (TFO)	No
具有向外延展檔案共用的SMB 3.0 (SO)	No
叢集共用磁碟區文件系統 (CsvFS)	Yes
彈性檔案系統 (ReFS)	Yes

SMB 不支援磁碟區管理功能。

尾端路徑元素

會忽略無效的尾端路徑專案。 針對遠端路徑，如果下列其中一個條件成立，則 (不只是尾端元素) 視為無效：

• 路徑的格式不正確。
• 路徑不存在。
• 目前用戶沒有路徑的存取權。

連接點和掛接的資料夾

如果指定的路徑周遊連接點， GetVolumePathName 會傳回連接點所參考的磁碟區。 例如，如果 W:\Adir 是指向C:\Adir的連接點，則會傳回 時叫用C:\的 W:\Adir\AfileGetVolumePathName。 如果指定的路徑周遊多個連接點，則會追蹤整個鏈結， 而 GetVolumePathName 會傳回鏈結中最後一個連接點所參考的磁碟區。

如果指定掛接資料夾或連接點的遠端路徑，則會將路徑剖析為遠端路徑，並忽略掛接的資料夾或連接點。 例如，如果 C:\Dir_C 已連結 D:\Dir_D 並 C: 對應至 X: 遠端電腦上的 ，則呼叫 GetVolumePathName 並在遠端電腦上指定 X:\Dir_C 會 X:\傳回 。

範例

針對下列一組範例，U： 會對應至遠端電腦 \\_YourComputer_\C$，而 Q 是本機磁碟驅動器。

指定的路徑	函式傳回
\\_YourComputer_\C$\Windows	\\_YourComputer_\C$\
\\?\UNC\_YourComputer_\C$\Windows	\\?\UNC\_YourComputer_\C$\
Q:\Windows	Q:\
\\?\Q:\Windows	\\?\Q:\
\\.\Q:\Windows	\\.\Q:\
\\?\UNC\W:\Windows	FALSE ，錯誤 123，因為指定的遠端路徑無效;W$ 共用不存在或沒有授與使用者存取權。
C:\COM2 存在) (	\\.\COM2\
C:\COM3 (不存在)	FALSE ，因為指定了不存在的 COM 裝置，所以發生錯誤 123。

針對下列一組範例，路徑包含無效的尾端路徑元素。

指定的路徑	函式傳回
G:\invalid (無效的路徑)	G:\
\\.\I:\aaa\invalid (無效的路徑)	\\.\I:\
\\_YourComputer_\C$\invalid (無效的尾端路徑元素)	\\_YourComputer_\C$\

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	fileapi.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll

另請參閱

• DeleteVolumeMountPoint
• GetFullPathName
• GetVolumeNameForVolumeMountPoint
• SetVolumeMountPoint
• 磁碟區管理功能
• 磁碟區裝入點