通过

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 参数指向的缓冲区必须足够大，才能存储 REMOTE_NAME_INFO 或 UNIVERSAL_NAME_INFO 结构中成员指向的 UNC 字符串。 如果缓冲区大小太小，则函数会失败并ERROR_MORE_DATA，lpBufferSize 参数指向的变量指示所需的缓冲区大小。

Windows Server 2003 和 Windows XP：此函数查询与登录会话关联的 MS-DOS 设备命名空间，因为身份验证 ID 会标识 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 标头将 WNetGetUniversalName 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows 2000 Professional [仅限桌面应用]
支持的最低服务器 Windows 2000 Server [仅限桌面应用]
目标平台 窗户
标头 winnetwk.h
库 Mpr.lib
DLL Mpr.dll

另请参阅

确定共享 的位置

REMOTE_NAME_INFO

UNIVERSAL_NAME_INFO

WNetAddConnection2

Windows 网络（WNet）概述

Windows 网络函数