getVolumePathNameA 函式 (winbase.h)
擷取裝載指定路徑的磁碟區裝入點。
語法
BOOL GetVolumePathNameA(
[in] LPCSTR lpszFileName,
[out] LPSTR lpszVolumePathName,
[in] DWORD cchBufferLength
);
參數
[in] lpszFileName
輸入路徑字串的指標。 絕對和相對檔案和目錄名稱，例如 “..”，在此路徑中都是可接受的。
如果您指定沒有磁碟區限定符的相對目錄或檔名， GetVolumePathName 會傳回開機磁碟區的驅動器號。
如果此參數是空字串 “”，則函式會失敗，但最後一個錯誤會設定為 ERROR_SUCCESS。
[out] lpszVolumePathName
接收輸入路徑之磁碟區裝入點之字串的指標。
[in] cchBufferLength
輸出緩衝區的長度，以 TCHAR 為單位。
傳回值
如果函式成功，則傳回非零的值。
如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
備註
如果傳遞指定的路徑， GetVolumePathName 會傳回磁碟區裝入點的路徑，這表示它會傳回指定路徑端點所在磁碟區的根目錄。
例如，假設您已在 C：\Mnt\Ddrive 掛接磁碟區 D，而磁碟區 E 掛接在 “C：\Mnt\Ddrive\Mnt\Edrive”。 也假設您有路徑為 「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 個字元，則傳回的值會是 “C：”;不過，如果 lpszVolumePathName 長度為 3 個字元，則傳回的值會是 “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\Afile叫用的 GetVolumePathName。
如果指定的路徑周遊多個連接點，則會追蹤整個鏈結，而 GetVolumePathName 會傳回鏈結中最後一個連接點所參考的磁碟區。
如果指定掛接資料夾或連接點的遠端路徑，則會將路徑剖析為遠端路徑，並忽略掛接的資料夾或連接點。 例如，如果 C:\Dir_C 鏈接至 D:\Dir_D 遠端電腦上且 C: 對應至 X: ，則呼叫 GetVolumePathName 並在遠端電腦上指定 X:\Dir_C 會 傳回 X：</code>。
範例
針對下列一組範例，U： 會對應至遠端電腦 \\YourComputer\C$，而 Q 是本機磁碟驅動器。
指定的路徑
函式傳回
\\YourComputer\C$\Windows
\\YourComputer\C$\
\\？\UNC\YourComputer\C$\Windows
\\？\UNC\YourComputer\C$\
Q：\Windows
Q:\
\\？\Q：\Windows
\\？\問：\
\\.\Q：\Windows
\\。\問：\
\\？\UNC\W：\Windows
FALSE ，錯誤 123，因為指定的遠端路徑無效;W$ 共用不存在或未授與使用者存取權。
C：\COM2 (存在)
\\.\COM2\
C：\COM3 (不存在)
FALSE ，錯誤 123，因為指定了不存在的 COM 裝置。
針對下列一組範例，路徑包含無效的尾端路徑專案。
指定的路徑
函式傳回
G：\invalid (無效的路徑)
G:\
\\.\I：\aaa\invalid (無效的路徑)
\\。\我：\
\\YourComputer\C$\invalid (無效的尾端路徑元素)
\\YourComputer\C$\
規格需求
需求
值
最低支援的用戶端
Windows XP [僅限傳統型應用程式]
最低支援的伺服器
Windows Server 2003 [僅限桌面應用程式]
目標平台
Windows
標頭
winbase.h (包含 Windows.h)
程式庫
Kernel32.lib
DLL
Kernel32.dll
另請參閱