通过

WNetAddConnection3A 函数 (winnetwk.h)

  • 项目

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

WNetAddConnection3 函数类似于 WNetAddConnection2 函数。 main区别在于，WNetAddConnection3 具有一个附加参数，它是网络资源提供程序可以用作对话框所有者窗口的窗口句柄。 WNetAddConnection2 函数和 WNetAddConnection3 函数取代了 WNetAddConnection 函数。

语法

DWORD WNetAddConnection3A(
  [in] HWND           hwndOwner,
  [in] LPNETRESOURCEA lpNetResource,
  [in] LPCSTR         lpPassword,
  [in] LPCSTR         lpUserName,
  [in] DWORD          dwFlags
);

参数

[in] hwndOwner

网络资源提供程序可以将该窗口的句柄用作对话框的所有者窗口。 如果在 dwFlags 参数中设置CONNECT_INTERACTIVE值，请使用此参数。

hwndOwner 参数可以为 NULL。 如果是，则调用 WNetAddConnection3 等效于调用 WNetAddConnection2 函数。

[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，则操作系统将尝试仅与命名的网络提供程序建立连接。

仅当知道要使用哪个网络提供商时，才应设置此成员。 否则，让操作系统确定网络名称映射到的网络提供程序。
 

WNetAddConnection3 函数忽略 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

一组连接选项。 当前定义了以下值。

值 含义
CONNECT_INTERACTIVE
 如果设置了此标志，则操作系统可能会出于身份验证目的与用户交互。
CONNECT_PROMPT
 此标志指示系统不要对用户名或密码使用任何默认设置，而不向用户提供替代项的机会。 除非还设置了CONNECT_INTERACTIVE，否则将忽略此标志。
CONNECT_REDIRECT
 建立连接时，此标志强制重定向本地设备。

如果 NETRESOURCE 的 lpLocalName 成员指定要重定向的本地设备，则此标志无效，因为操作系统仍会尝试重定向指定的设备。 当操作系统自动选择本地设备时， dwType 成员不得等于RESOURCETYPE_ANY。

如果未设置此标志，则仅当网络需要重定向本地设备时，才会自动选择本地设备进行重定向。

Windows Server 2003 和 Windows XP： 当系统自动分配网络驱动器号时，将分配以 Z：开头的字母，然后以 Y：开头，以 C：结尾。 这可以减少每个登录驱动器号 (（例如网络驱动器号) ）与全局驱动器号 (（如磁盘驱动器) ）之间的冲突。 请注意，早期版本的 Windows 分配的驱动器号以 C： 开头，以 Z： 结尾。
CONNECT_UPDATE_PROFILE
 应记住网络资源连接。

如果设置了此位标志，则操作系统会在用户登录时自动尝试还原连接。

操作系统仅记住重定向本地设备的成功连接。 它不会记住不成功的连接或无设备连接。 (当 lpLocalName 成员为 NULL 或指向空字符串时，将发生无设备连接。)

如果此位标志为清除，则操作系统不会在登录时自动还原连接。
CONNECT_COMMANDLINE
 如果设置了此标志，操作系统将使用命令行而不是图形用户界面（ (GUI) ）提示用户进行身份验证。 除非还设置了CONNECT_INTERACTIVE，否则将忽略此标志。

Windows 2000/NT 和 Windows Me/98/95： 不支持此值。
CONNECT_CMD_SAVECRED
 如果设置了此标志，并且操作系统提示输入凭据，则凭据管理器应保存凭据。 如果为调用方登录会话禁用了凭据管理器，或者如果网络提供程序不支持保存凭据，则忽略此标志。 除非设置了CONNECT_COMMANDLINE标志，否则也会忽略此标志。

Windows 2000/NT 和 Windows Me/98/95： 不支持此值。

返回值

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

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

返回代码 说明
ERROR_ACCESS_DENIED
 调用方无权访问网络资源。
ERROR_ALREADY_ASSIGNED
 lpLocalName 成员指定的本地设备已连接到网络资源。
ERROR_BAD_DEV_TYPE
 本地设备的类型和网络资源类型不匹配。
ERROR_BAD_DEVICE
 lpLocalName 指定的值无效。
ERROR_BAD_NET_NAME
 任何网络资源提供程序都不接受 由 lpRemoteName 成员指定的值，原因是资源名称无效，或者无法找到命名的资源。
ERROR_BAD_PROFILE
 用户配置文件的格式不正确。
ERROR_BAD_PROVIDER
 lpProvider 成员指定的值与任何提供程序都不匹配。
ERROR_BUSY
 路由器或提供程序正忙，可能正在初始化。 调用方应重试。
ERROR_CANCELLED
 用户通过某个网络资源提供程序中的对话框或被调用的资源取消了建立连接的尝试。
ERROR_CANNOT_OPEN_PROFILE
 系统无法打开用户配置文件来处理持久连接。
ERROR_DEVICE_ALREADY_REMEMBERED
 lpLocalName 成员指定的设备的条目已在用户配置文件中。
ERROR_EXTENDED_ERROR
 发生特定于网络的错误。 调用 WNetGetLastError 函数以获取错误说明。
ERROR_INVALID_PASSWORD
 指定的密码无效，并且未设置CONNECT_INTERACTIVE标志。
ERROR_NO_NET_OR_BAD_PATH
 由于网络组件未启动或无法使用指定名称，因此无法执行该操作。
ERROR_NO_NETWORK
 网络不可用。

注解

WNetUseConnection 函数类似于 WNetAddConnection3 函数。 main区别在于，WNetUseConnection 可以自动选择要重定向到网络资源的未使用的本地设备。

在 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 运行的服务调用 WNetAddConnection3 函数，则映射的驱动器对所有用户登录会话可见。

对于 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 中指定的显式用户凭据调用 WNetAddConnection3 函数，以便与特定服务器上的网络资源建立连接，然后使用这些参数之一作为 NULL (再次调用，以使用默认用户名或默认密码) 到同一服务器，则带有 的调用将失败。 返回的错误将 ERROR_BAD_USERNAME 或 ERROR_INVALID_PASSWORD。

注意

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

要求

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

另请参阅

NETRESOURCE

WNetAddConnection2

WNetCancelConnection2

WNetGetConnection

WNetUseConnection

Windows 网络 (WNet) 概述

Windows 网络函数