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 设备命名空间，因为 MS-DOS 设备由 AuthenticationID 标识。 (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 [仅限桌面应用]
目标平台 Windows
标头 winnetwk.h
Library Mpr.lib
DLL Mpr.dll

另请参阅

确定共享的位置

REMOTE_NAME_INFO

UNIVERSAL_NAME_INFO

WNetAddConnection2

Windows 网络 (WNet) 概述

Windows 网络函数