WNetAddConnection2A 函数 (winnetwk.h)
WNetAddConnection2 函数与网络资源建立连接，并且可以将本地设备重定向到网络资源。
WNetAddConnection2 函数取代了 WNetAddConnection 函数。 如果可以将句柄传递给网络资源提供程序可以用作对话框的所有者窗口的窗口，请改为调用 WNetAddConnection3 函数。
语法
DWORD WNetAddConnection2A(
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
参数
[in] lpNetResource
指向 NETRESOURCE 结构的指针，该结构指定建议连接的详细信息，例如有关网络资源、本地设备和网络资源提供程序的信息。
必须指定 NETRESOURCE 结构的以下成员。
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 头文件中定义。 当前可以使用以下值。
| 值 | 含义 |
|---|---|
|
应记住网络资源连接。
如果设置了此位标志，操作系统会在用户登录时自动尝试还原连接。 操作系统仅记住重定向本地设备的成功连接。 它不会记住不成功的连接或无设备连接。 (当 lpLocalName 成员为 NULL 或指向空字符串时，将发生无设备连接。) 如果此位标志明确，则操作系统不会在用户登录时尝试还原连接。 |
|
网络资源连接不应放在最近的连接列表中。
如果设置了此标志并成功添加连接，则仅当网络资源连接具有与之关联的重定向本地设备时，网络资源连接才会放入最近的连接列表中。 |
|
不应记住网络资源连接。
如果设置了此标志，则当用户再次登录时，操作系统不会尝试还原连接。 |
|
如果设置了此标志，则操作系统可能会出于身份验证目的与用户交互。 |
|
此标志指示系统不要对用户名或密码使用任何默认设置，而不向用户提供替代项的机会。 除非还设置了CONNECT_INTERACTIVE，否则将忽略此标志。 |
|
建立连接时，此标志强制重定向本地设备。
如果 NETRESOURCE 的 lpLocalName 成员指定要重定向的本地设备，则此标志不起作用，因为操作系统仍在尝试重定向指定的设备。 当操作系统自动选择本地设备时， dwType 成员不得等于 RESOURCETYPE_ANY。 如果未设置此标志，则仅当网络需要重定向本地设备时，才会自动选择本地设备进行重定向。 Windows Server 2003 和 Windows XP： 当系统自动分配网络驱动器号时，将分配以 Z：开头、Y：、以 C：结尾的字母。 这可以减少每个登录驱动器号 (（例如网络驱动器号) ）与全局驱动器号（如磁盘驱动器 () ）之间的冲突。 请注意，早期版本的 Windows 分配的驱动器号以 C： 开头，以 Z：结尾。 |
|
如果设置了此标志，则操作系统不会开始使用新媒体尝试建立连接 (启动新的拨号连接，例如) 。 |
|
如果设置了此标志，操作系统将使用命令行（而不是图形用户界面）提示用户进行身份验证， (GUI) 。 除非还设置了CONNECT_INTERACTIVE，否则将忽略此标志。
Windowsxp： Windows XP 及更高版本支持此值。 |
|
如果设置了此标志，并且操作系统提示输入凭据，则凭据应由凭据管理器保存。 如果为调用方登录会话禁用了凭据管理器，或者网络提供程序不支持保存凭据，则会忽略此标志。 除非还设置了CONNECT_INTERACTIVE，否则将忽略此标志。 除非设置了 CONNECT_COMMANDLINE 标志，否则也会忽略此标志。
Windowsxp： Windows XP 及更高版本支持此值。 |
|
如果设置了此标志，并且操作系统提示输入凭据，则凭据管理器会重置凭据。 如果为调用方登录会话禁用了凭据管理器，或者如果网络提供程序不支持保存凭据，则忽略此标志。 除非设置了CONNECT_COMMANDLINE标志，否则也会忽略此标志。
Windows Vista： Windows Vista 及更高版本支持此值。 |
返回值
如果函数成功，则返回值NO_ERROR。
如果函数失败，则返回值可以是以下错误代码之一或 系统错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
调用方无权访问网络资源。 |
|
lpLocalName 成员指定的本地设备已连接到网络资源。 |
|
本地设备的类型和网络资源类型不匹配。 |
|
指定的设备名称无效。 如果 lpNetResource 参数指向的 NETRESOURCE 结构的 lpLocalName 成员指定不可重定向的设备，则返回此错误。 |
|
找不到网络名称。 如果 lpNetResource 参数指向的 NETRESOURCE 结构的 lpRemoteName 成员指定了任何网络资源提供程序都不接受的资源，则返回此值，原因是资源名称为空、无效，或者无法找到命名资源。 |
|
用户配置文件的格式不正确。 |
|
指定的网络提供程序名称无效。 如果 lpNetResource 参数指向的 NETRESOURCE 结构的 lpProvider 成员指定的值与任何网络提供程序都不匹配，则返回此错误。 |
|
指定的用户名无效。 |
|
路由器或提供程序正忙，可能正在初始化。 调用方应重试。 |
|
用户通过某个网络资源提供程序中的对话框或被调用的资源取消了建立连接的尝试。 |
|
系统无法打开用户配置文件来处理持久连接。 |
|
本地设备名称与另一个网络资源存在已记住的连接。 如果 lpNetResource 参数指向的 NETRESOURCE 结构的 lpLocalName 成员指定的设备的条目指定了与 lpNetResource 参数中指定的连接不同的连接，则返回此错误。 |
|
发生特定于网络的错误。 调用 WNetGetLastError 函数以获取错误说明。 |
|
尝试访问无效地址。 如果 dwFlags 参数指定值 CONNECT_REDIRECT，但未指定 lpNetResource 参数指向的 NETRESOURCE 结构的 lpLocalName 成员，则返回此错误。 |
|
参数不正确。 如果 lpNetResource 参数指向的 NETRESOURCE 结构的 dwType 成员指定的值不是 RESOURCETYPE_DISK、RESOURCETYPE_PRINT 或 RESOURCETYPE_ANY，则返回此错误。 如果 dwFlags 参数指定的值不正确或未知，也会返回此错误。 |
|
指定的密码无效，并且未设置CONNECT_INTERACTIVE标志。 |
|
由于用户名未知或密码错误而导致登录失败。 |
|
没有网络提供商接受给定的网络路径。 如果没有网络提供程序识别到 lpNetResource 参数指向的 NETRESOURCE 结构的 lpRemoteName 成员，则返回此错误。 |
|
网络不可用。 |
|
使用 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 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈