共用方式為

WNetGetUniversalNameA 函式 (winnetwk.h)

  • 發行項

WNetGetUniversalName函式會採用網路資源的磁片磁碟機型路徑，並傳回包含更通用名稱形式的資訊結構。

語法

DWORD WNetGetUniversalNameA(
  [in]      LPCSTR  lpLocalPath,
  [in]      DWORD   dwInfoLevel,
  [out]     LPVOID  lpBuffer,
  [in, out] LPDWORD lpBufferSize
);

參數

[in] lpLocalPath

以磁片磁碟機為基礎的網路資源路徑之常數 Null 終止字串的指標。

例如，如果磁片磁碟機 H 已對應到網路磁碟機機共用，而感興趣的網路資源是該共用目錄 \Win32\Examples 中名為 Sample.doc 的檔案，磁片磁碟機型路徑會 H:\Win32\Examples\Sample.doc。

[in] dwInfoLevel

函式儲存在 lpBuffer 參數所指向之緩衝區中的結構類型。 此參數可以是 Winnetwk.h 標頭檔中定義的下列其中一個值。

值 意義
UNIVERSAL_NAME_INFO_LEVEL
 函式會將 UNIVERSAL_NAME_INFO 結構儲存在緩衝區中。
REMOTE_NAME_INFO_LEVEL
 函式會將 REMOTE_NAME_INFO 結構儲存在緩衝區中。
 

UNIVERSAL_NAME_INFO結構指向通用命名慣例， (UNC) 名稱字串。

REMOTE_NAME_INFO結構指向 UNC 名稱字串和兩個額外的連接字串。 如需詳細資訊，請參閱接下來的＜備註＞一節。

[out] lpBuffer

接收 dwInfoLevel 參數所指定結構的緩衝區指標。

[in, out] lpBufferSize

變數的指標，指定 lpBuffer 參數所指向緩衝區的大小，以位元組為單位。

如果函式成功，它會將 lpBufferSize 指向的變數設定為儲存在緩衝區中的位元組數目。 如果函式因為緩衝區太小而失敗，這個位置會收到所需的緩衝區大小，而且函式會傳回ERROR_MORE_DATA。

傳回值

如果函式成功，傳回值會NO_ERROR。

如果函式失敗，傳回值是 系統錯誤碼，例如下列其中一個值。

傳回碼 描述
ERROR_BAD_DEVICE
 lpLocalPath參數指向的字串無效。
ERROR_CONNECTION_UNAVAIL
 遠端裝置目前沒有連線，但 (持續) 連線。
ERROR_EXTENDED_ERROR
 發生網路特定錯誤。 使用 WNetGetLastError 函 式來取得錯誤的描述。
ERROR_MORE_DATA
 由 lpBuffer參數指向的緩衝區太小。 函式會將 lpBufferSize 參數指向的變數設定為所需的緩衝區大小。 後續呼叫可取得更多專案。
ERROR_NOT_SUPPORTED
 dwInfoLevel參數會設定為 UNIVERSAL_NAME_INFO_LEVEL，但網路提供者不支援 UNC 名稱。 (沒有任何網路提供者支援此函式。)
ERROR_NO_NET_OR_BAD_PATH
 網路提供者都不會將本機名稱辨識為具有連線。 不過，至少一個連線所屬的提供者無法使用網路。
ERROR_NO_NETWORK
 網路無法使用。
ERROR_NOT_CONNECTED
 lpLocalPath參數指定的裝置不會重新導向。

備註

本機磁片磁碟機型路徑的通用形式會以明確且與電腦無關的方式識別網路資源。 接著，可以將名稱傳遞給其他電腦上的進程，讓這些進程可以取得資源的存取權。

WNetGetUniversalName函式目前支援一種通用名稱形式：通用命名慣例 (UNC) 名稱，如下所示：

\\servername\sharename\path\file

使用上述 lpLocalPath 參數描述中的範例，如果共用網路磁碟機機位於名為 COOLSERVER 的伺服器上，且共用名稱稱為 HOTSHARE，則磁片磁碟機型名稱為 H:\Win32\Examples\Sample.doc 的網路資源 UNC 名稱如下：

\\coolserver\hotshare\win32\examples\sample.doc

UNIVERSAL_NAME_INFO結構包含 UNC 名稱字串的指標。 REMOTE_NAME_INFO結構也包含 UNC 名稱字串的指標，以及兩個其他實用字串的指標。 例如，進程可以將 REMOTE_NAME_INFO 結構的 lpszConnectionInfo 成員傳遞至 WNetAddConnection2 函式，以將本機裝置連線到網路資源。 然後，進程可以將 lpszRemainingPath 成員指向的字串附加至本機裝置字串。 產生的字串可以傳遞至需要磁片磁碟機型路徑的函式。

lpLocalPath參數不需要指定已經存在於遠端資源上的路徑或資源。 例如， lpLocalPath 參數可以指定 和 資料夾、資料夾階層或目前不存在的檔案。 在這些情況下，WNetGetUniversalName函式會傳回更通用的名稱形式。

lpBuffer 參數所指向的緩衝區大小，並在lpBufferSize參數中指定的大小必須遠大於REMOTE_NAME_INFO或UNIVERSAL_NAME_INFO結構的大小。 lpBuffer參數所指向的緩衝區必須夠大，才能將成員指向的 UNC 字串儲存在REMOTE_NAME_INFO或UNIVERSAL_NAME_INFO結構中。 如果緩衝區大小太小，則函式會因為ERROR_MORE_DATA而失敗，而 lpBufferSize 參數所指向的變數表示所需的緩衝區大小。

Windows Server 2003 和 Windows XP： 此函式會查詢與登入會話相關聯的 MS-DOS 裝置命名空間，因為驗證識別碼會識別 MS-DOS 裝置。 (AuthenticationID 是與登入會話相關聯的 本機唯一識別碼或 LUID。) 這可能會影響呼叫其中一個 WNet 函式的應用程式，以在一個使用者登入下建立網路磁碟機號，但在不同的使用者登入下查詢現有的網路磁碟機號。 這種情況的範例可能是當使用者的第二次登入是在登入會話內建立時，例如呼叫 CreateProcessAsUser 函式，而第二次登入會執行呼叫 GetLogicalDrives 函 式的應用程式。 GetLogicalDrives 不會傳回第一次登入下 WNet 函式所建立的網路磁碟機號。 請注意，在上述範例中，第一個登入會話仍然存在，而且此範例可以套用至任何登入會話，包括終端機服務會話。 如需詳細資訊，請參閱 定義 MS-DOS 裝置名稱。

範例

下列程式碼範例說明如何使用 WNetGetUniversalName 函式，擷取與網路資源磁片磁碟機型路徑相關聯的通用 UNC 名稱字串。

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")

#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>

int wmain(int argc, wchar_t * argv[])
{
    DWORD dwRetVal;

    WCHAR Buffer[1024];
    DWORD dwBufferLength = 1024;
       
    UNIVERSAL_NAME_INFO * unameinfo;
    REMOTE_NAME_INFO *remotenameinfo;
    
    wprintf(L"Calling WNetGetUniversalName with Local Path = %s\n", argv[1]);

    unameinfo = (UNIVERSAL_NAME_INFO *) &Buffer;
    dwRetVal = WNetGetUniversalName(argv[1], UNIVERSAL_NAME_INFO_LEVEL, (LPVOID) unameinfo, &dwBufferLength );
    //
    // If the call succeeds, print the user information.
    //
    if (dwRetVal == NO_ERROR) {

        wprintf(L"WNetGetUniversalName returned success for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL\n");
        wprintf(L"\tUniversal name = %s\n", unameinfo->lpUniversalName);
    }

    else {
        wprintf(L"WNetGetUser failed for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
    }


    remotenameinfo = (REMOTE_NAME_INFO *) &Buffer;
    dwRetVal = WNetGetUniversalName(argv[1], REMOTE_NAME_INFO_LEVEL, 
        (LPVOID) remotenameinfo, &dwBufferLength );
    //
    // If the call succeeds, print the user information.
    //
    if (dwRetVal == NO_ERROR) {

        wprintf(L"WNetGetUniversalName returned success for InfoLevel=REMOTE_NAME_INFO_LEVEL\n");
        wprintf(L"\tUniversal name = %s\n", remotenameinfo->lpUniversalName);
        wprintf(L"\tConnection name = %s\n", remotenameinfo->lpConnectionName);
        wprintf(L"\tRemaining path = %s\n", remotenameinfo->lpRemainingPath);
    }

    else {
        wprintf(L"WNetGetUser failed for InfoLevel=REMOTE_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
    }
}

注意

winnetwk.h 標頭會根據 UNICODE 預處理器常數的定義，將 WNetGetUniversalName 定義為別名，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

   
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 winnetwk.h
程式庫 Mpr.lib
Dll Mpr.dll

另請參閱

判斷共用的位置

REMOTE_NAME_INFO

UNIVERSAL_NAME_INFO

WNetAddConnection2

Windows 網路 (WNet) 概觀

Windows 網路功能