WNetAddConnection2W 函数 (winnetwk.h)

项目
08/27/2023

WNetAddConnection2 函数与网络资源建立连接，并且可以将本地设备重定向到网络资源。

WNetAddConnection2 函数取代 WNetAddConnection 函数。如果可以将句柄传递给网络资源提供程序可以用作对话框的所有者窗口的窗口，请改为调用 WNetAddConnection3 函数。

语法

DWORD WNetAddConnection2W(
  [in] LPNETRESOURCEW lpNetResource,
  [in] LPCWSTR        lpPassword,
  [in] LPCWSTR        lpUserName,
  [in] DWORD          dwFlags
);

参数

[in] lpNetResource

指向 NETRESOURCE 结构的指针，该结构指定建议的连接的详细信息，例如有关网络资源、本地设备和网络资源提供程序的信息。

必须指定 NETRESOURCE 结构的以下成员。

成员	含义
dwType	要连接到的网络资源的类型。如果 lpLocalName 成员指向非空字符串，则此成员可以等于 RESOURCETYPE_DISK 或 RESOURCETYPE_PRINT。如果 lpLocalName 为 NULL，或者它指向空字符串，则 dwType 可以等于 RESOURCETYPE_DISK、RESOURCETYPE_PRINT 或 RESOURCETYPE_ANY。尽管此成员是必需的，但网络服务提供商可能会忽略其信息。
lpLocalName	指向以 null 结尾的字符串的指针，该字符串指定要重定向的本地设备的名称，例如“F：”或“LPT1”。字符串以不区分大小写的方式进行处理。如果字符串为空，或者 lpLocalName 为 NULL，则该函数将建立与网络资源的连接，而无需重定向本地设备。
lpRemoteName	指向以 null 结尾的字符串的指针，该字符串指定要连接到的网络资源。字符串的长度最多可为 MAX_PATH 个字符，并且必须遵循网络提供商的命名约定。
lpProvider	指向以 null 结尾的字符串的指针，该字符串指定要连接到的网络提供程序。如果 lpProvider 为 NULL，或者如果它指向空字符串，则操作系统会尝试通过分析 lpRemoteName 成员指向的字符串来确定正确的提供程序。如果此成员不为 NULL，则操作系统将尝试仅与命名的网络提供程序建立连接。仅当知道要使用的网络提供商时，才应设置此成员。否则，让操作系统确定网络名称映射到哪个提供程序。

WNetAddConnection2 函数忽略 NETRESOURCE 结构的其他成员。

[in] lpPassword

指向以 null 结尾的常量字符串的指针，该字符串指定要在建立网络连接时使用的密码。

如果 lpPassword 为 NULL，则该函数使用与 lpUserName 参数指定的用户关联的当前默认密码。

如果 lpPassword 指向空字符串，则函数不使用密码。

如果连接因密码无效而失败，并且 dwFlags 参数中设置了CONNECT_INTERACTIVE值，则该函数将显示一个对话框，要求用户键入密码。

Windows Me/98/95： 此参数必须为 NULL 或空字符串。

[in] lpUserName

指向以 null 结尾的常量字符串的指针，该字符串指定用于建立连接的用户名。

如果 lpUserName 为 NULL，则该函数使用默认用户名。 (进程的用户上下文提供默认用户名。)

当用户想要连接到为其分配了用户名或帐户（而不是默认用户名或帐户）的网络资源时，将指定 lpUserName 参数。

用户名字符串表示安全上下文。它可能特定于网络提供商。

Windows Me/98/95： 此参数必须为 NULL 或空字符串。

[in] dwFlags

一组连接选项。连接选项的可能值在 Winnetwk.h 头文件中定义。当前可以使用以下值。

值	含义
CONNECT_UPDATE_PROFILE 0x00000001	应记住网络资源连接。如果设置了此位标志，则操作系统会在用户登录时自动尝试还原连接。操作系统仅记住重定向本地设备的成功连接。它不会记住不成功的连接或无设备连接。 (当 lpLocalName 成员为 NULL 或指向空字符串时，将发生无设备连接。) 如果此位标志清除，则操作系统不会在用户登录时尝试还原连接。
CONNECT_UPDATE_RECENT 0x00000002	网络资源连接不应放在最近的连接列表中。如果设置了此标志并成功添加连接，则仅当网络资源连接具有关联的重定向本地设备时，才会将网络资源连接置于最近的连接列表中。
CONNECT_TEMPORARY 0x00000004	不应记住网络资源连接。如果设置了此标志，则当用户再次登录时，操作系统不会尝试还原连接。
CONNECT_INTERACTIVE 0x00000008	如果设置了此标志，则操作系统可能会出于身份验证目的与用户交互。
CONNECT_PROMPT 0x00000010	此标志指示系统不要对用户名或密码使用任何默认设置，而不向用户提供替代项的机会。除非还设置了CONNECT_INTERACTIVE，否则将忽略此标志。
CONNECT_REDIRECT 0x00000080	建立连接时，此标志强制重定向本地设备。如果 NETRESOURCE 的 lpLocalName 成员指定要重定向的本地设备，则此标志无效，因为操作系统仍会尝试重定向指定的设备。当操作系统自动选择本地设备时， dwType 成员不得等于RESOURCETYPE_ANY。如果未设置此标志，则仅当网络需要重定向本地设备时，才会自动选择本地设备进行重定向。 Windows Server 2003 和 Windows XP：当系统自动分配网络驱动器号时，将分配以 Z：开头的字母，然后以 Y：开头，以 C：结尾。这可以减少每个登录驱动器号 (（例如网络驱动器号) ）与全局驱动器号 (（如磁盘驱动器) ）之间的冲突。请注意，早期版本的 Windows 分配的驱动器号以 C：开头，以 Z：结尾。
CONNECT_CURRENT_MEDIA 0x00000200	如果设置了此标志，则操作系统不会开始使用新媒体来尝试建立连接 (启动新的拨号连接，例如) 。
CONNECT_COMMANDLINE 0x00000800	如果设置了此标志，操作系统将使用命令行而不是图形用户界面（ (GUI) ）提示用户进行身份验证。除非还设置了CONNECT_INTERACTIVE，否则将忽略此标志。 Windowsxp：此值在 Windows XP 及更高版本上受支持。
CONNECT_CMD_SAVECRED 0x00001000	如果设置了此标志，并且操作系统提示输入凭据，则凭据管理器应保存凭据。如果为调用方登录会话禁用了凭据管理器，或者如果网络提供程序不支持保存凭据，则忽略此标志。除非还设置了CONNECT_INTERACTIVE，否则将忽略此标志。除非设置了CONNECT_COMMANDLINE标志，否则也会忽略此标志。 Windowsxp：此值在 Windows XP 及更高版本上受支持。
CONNECT_CRED_RESET 0x00002000	如果设置了此标志，并且操作系统提示输入凭据，则凭据管理器将重置凭据。如果为调用方登录会话禁用了凭据管理器，或者如果网络提供程序不支持保存凭据，则忽略此标志。除非设置了CONNECT_COMMANDLINE标志，否则也会忽略此标志。 Windows Vista： Windows Vista 及更高版本支持此值。

返回值

如果函数成功，则返回值NO_ERROR。

如果函数失败，则返回值可以是以下错误代码之一或系统错误代码之一。

返回代码	说明
ERROR_ACCESS_DENIED	调用方无权访问网络资源。
ERROR_ALREADY_ASSIGNED	lpLocalName 成员指定的本地设备已连接到网络资源。
ERROR_BAD_DEV_TYPE	本地设备的类型和网络资源类型不匹配。
ERROR_BAD_DEVICE	指定的设备名称无效。如果 lpNetResource 参数指向的 NETRESOURCE 结构的 lpLocalName 成员指定不可重定向的设备，则返回此错误。
ERROR_BAD_NET_NAME	找不到网络名称。如果 lpNetResource 参数指向的 NETRESOURCE 结构的 lpRemoteName 成员指定了任何网络资源提供程序都不接受的资源，则返回此值，原因是资源名称为空、无效，或者无法找到命名资源。
ERROR_BAD_PROFILE	用户配置文件的格式不正确。
ERROR_BAD_PROVIDER	指定的网络提供程序名称无效。如果 lpNetResource 参数指向的 NETRESOURCE 结构的 lpProvider 成员指定的值与任何网络提供程序都不匹配，则返回此错误。
ERROR_BAD_USERNAME	指定的用户名无效。
ERROR_BUSY	路由器或提供程序正忙，可能正在初始化。调用方应重试。
ERROR_CANCELLED	用户通过某个网络资源提供程序中的对话框或被调用的资源取消了建立连接的尝试。
ERROR_CANNOT_OPEN_PROFILE	系统无法打开用户配置文件来处理持久连接。
ERROR_DEVICE_ALREADY_REMEMBERED	本地设备名称与另一个网络资源存在已记住的连接。如果 lpNetResource 参数指向的 NETRESOURCE 结构的 lpLocalName 成员指定的设备的条目指定了与 lpNetResource 参数中指定的连接不同的连接，则返回此错误。
ERROR_EXTENDED_ERROR	发生特定于网络的错误。调用 WNetGetLastError 函数以获取错误说明。
ERROR_INVALID_ADDRESS	尝试访问无效地址。如果 dwFlags 参数指定值 CONNECT_REDIRECT，但未指定 lpNetResource 参数指向的 NETRESOURCE 结构的 lpLocalName 成员，则返回此错误。
ERROR_INVALID_PARAMETER	参数不正确。如果 lpNetResource 参数指向的 NETRESOURCE 结构的 dwType 成员指定的值不是 RESOURCETYPE_DISK、RESOURCETYPE_PRINT 或 RESOURCETYPE_ANY，则返回此错误。如果 dwFlags 参数指定的值不正确或未知，也会返回此错误。
ERROR_INVALID_PASSWORD	指定的密码无效，并且未设置CONNECT_INTERACTIVE标志。
ERROR_LOGON_FAILURE	由于用户名未知或密码错误而导致登录失败。
ERROR_NO_NET_OR_BAD_PATH	没有网络提供商接受给定的网络路径。如果没有网络提供程序识别到 lpNetResource 参数指向的 NETRESOURCE 结构的 lpRemoteName 成员，则返回此错误。
ERROR_NO_NETWORK	网络不可用。
其他	使用 FormatMessage 获取返回错误的消息字符串。

注解

在 Windows Server 2003 和 Windows XP 上，WNet 函数在与登录会话关联的 MS-DOS 设备命名空间中创建和删除网络驱动器号，因为 MS-DOS 设备由 AuthenticationID (标识
与登录会话关联的本地唯一标识符或 LUID。) 这可能会影响调用其中一个 WNet 函数以在一个用户登录下创建网络驱动器号的应用程序，但在其他用户登录下查询现有网络驱动器号。这种情况的一个示例可能是在登录会话中创建用户的第二次登录（例如，通过调用 CreateProcessAsUser 函数），第二次登录运行调用 GetLogicalDrives 函数的应用程序。对 GetLogicalDrives 函数的 调用不会返回 WNet 函数调用在第一次登录时创建的网络驱动器号。请注意，在前面的示例中，第一个登录会话仍然存在，该示例可以应用于任何登录会话，包括终端服务会话。有关详细信息，请参阅定义 MS-DOS 设备名称。

在 Windows Server 2003 和 Windows XP 上，如果作为 LocalSystem 运行的服务调用 WNetAddConnection2 函数，则映射的驱动器对所有用户登录会话都可见。

对于 Microsoft 网络提供程序， lpNetResource 参数指向的 NETRESOURCE 结构的 lpRemoteName 成员可以包含一个以点十进制表示法表示的 IPv4 地址。共享的示例可能如下所示：

\192.168.1.1\share

对于 Windows Vista 及更高版本上的 Microsoft 网络提供程序， lpNetResource 参数指向的 NETRESOURCE 结构的 lpRemoteName 成员可以包含 IPv6 地址。但是，必须使用 IPv6 文本格式，以便正确分析 IPv6 地址。 IPv6 文本地址的格式如下：

ipv6-address，其中“：”字符替换为“-”字符，后跟“.ipv6-literal.net”字符串。

例如，对于以下 IPv6 地址：

2001:4898:9:3:c069:aa97:fe76:2449

共享的示例可能如下所示：

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

其他网络提供程序可能支持包含 IPv4 或 IPv6 地址的 lpNetResource 参数所指向的 NETRESOURCE 结构的 lpRemoteName 成员，但这由特定的网络提供程序决定。

Windows 7 和 Windows Server 2008 R2： 如果使用 pUsername 和 lpPassword 中指定的显式用户凭据调用 WNetAddConnection2 函数，以便与特定服务器上的网络资源建立连接，然后使用这些参数之一再次调用 NULL (以使用同一服务器的默认用户名或默认密码) ，则带有的调用将失败。返回的错误将 ERROR_BAD_USERNAME 或 ERROR_INVALID_PASSWORD。

示例

下面的代码示例演示如何使用 WNetAddConnection2 函数建立与网络资源的连接。

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

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

// Need to link with Netapi32.lib and Mpr.lib

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

    DWORD dwRetVal;

    NETRESOURCE nr;
    DWORD dwFlags;

    if (argc != 5) {
        wprintf(L"Usage: %s <localname> <remotename> <username> <password>\n",
                argv[0]);
        wprintf(L"       %s X: \\\\contoso\\public testuser testpasswd\n",
                argv[0]);
        exit(1);
    }

    wprintf(L"Calling WNetAddConnection2 with\n");
    wprintf(L"  lpLocalName = %s\n", argv[1]);
    wprintf(L"  lpRemoteName = %s\n", argv[2]);
    wprintf(L"  lpUsername = %s\n", argv[3]);
    wprintf(L"  lpPassword = %s\n", argv[4]);

// Zero out the NETRESOURCE struct
    memset(&nr, 0, sizeof (NETRESOURCE));

// Assign our values to the NETRESOURCE structure.

    nr.dwType = RESOURCETYPE_ANY;
    nr.lpLocalName = argv[1];
    nr.lpRemoteName = argv[2];
    nr.lpProvider = NULL;

// Assign a value to the connection options
    dwFlags = CONNECT_UPDATE_PROFILE;
//
// Call the WNetAddConnection2 function to assign
//   a drive letter to the share.
//
    dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);
//
// If the call succeeds, inform the user; otherwise,
//  print the error.
//
    if (dwRetVal == NO_ERROR)
        wprintf(L"Connection added to %s\n", nr.lpRemoteName);
    else
        wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);

    exit(1); 
}

有关演示如何使用 WNetAddConnection2 函数连接到网络资源的其他代码示例，请参阅添加网络连接和将驱动器分配到共享。

注意

winnetwk.h 标头将 WNetAddConnection2 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

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