6 views
| 平台 SDK: Windows 网络 |
WNetAddConnection3
WNetAddConnection3函数连接到网络资源。该函数可以将本地设备重定向到网络资源。
WNetAddConnection3函数类似于WNetAddConnection2函数。主要区别在于WNetAddConnection3有一个附加参数，即网络资源提供者可用作对话框所有者窗口的窗口句柄。WNetAddConnection2函数和WNetAddConnection3函数取代WNetAddConnection函数。
DWORD WNetAddConnection3( HWND hwndOwner, // 所有者窗口 LPNETRESOURCE lpNetResource, // 连接细节 LPTSTR lpPassword, // 密码字符串 LPTSTR lpUserName, // 用户名字符串 DWORD dwFlags // 连接选项 );
参数
hwndOwner
[in] 指定网络资源提供者可以用作对话框所有者窗口的窗口句柄。 如果您在dwFlags参数中设置了CONNECT_INTERACTIVE值，请使用此参数。
hwndOwner参数可以是NULL。 如果是，则调用WNetAddConnection3相当于调用WNetAddConnection2函数。
lpNetResource
[in] 指向NETRESOURCE结构的指针，指定建议的连接的详细信息，例如关于网络资源，本地设备和网络资源提供者的信息。
您必须指定NETRESOURCE结构的以下成员。
成员 描述 dwType 指定要连接的网络资源的类型。 如果lpLocalName成员指向非空字符串，则此成员可以等于RESOURCETYPE_DISK或RESOURCETYPE_PRINT。
如果lpLocalName为NULL，或者指向空字符串，则dwType可以等于RESOURCETYPE_DISK，RESOURCETYPE_PRINT或RESOURCETYPE_ANY。
虽然此成员是必需的，但其信息可能会被网络服务提供商忽略。
lpLocalName 指向一个空终止的字符串，指定要重定向的本地设备的名称， 例如 "F:" or "LPT1"。字符串以不区分大小写的方式处理。 如果字符串为空或者lpLocalName为NULL，则该函数将连接到网络资源而不重定向本地设备。
lpRemoteName 指向一个空终止的字符串，它指定要连接的网络资源。 该字符串的长度可以达到MAX_PATH个字符，并且必须遵循网络提供商的命名约定。 lpProvider 指向一个以null结尾的字符串，它指定要连接的网络提供者。 如果lpProvider为NULL，或者它指向一个空字符串，操作系统会尝试通过解析由lpRemoteName成员指向的字符串来确定正确的提供程序。
如果此成员不为NULL，则操作系统将尝试仅与指定的网络提供者建立连接。
只有当您知道您要使用哪个网络提供商时，才应设置此成员。 否则，让操作系统确定网络名称映射到哪个网络提供者。
WNetAddConnection3函数忽略NETRESOURCE结构的其他成员。
lpPassword
[in] 指向以空字符结尾的字符串，指定用于建立网络连接的密码。
如果lpPassword为NULL，则该函数使用与由lpUserName参数指定的用户关联的当前默认密码。
如果lpPassword指向一个空字符串，则该函数不使用密码。
如果连接由于密码无效而失败，并且在dwFlags参数中设置了CONNECT_INTERACTIVE值，则该函数将显示一个对话框，要求用户输入密码。
Windows 95/98/Me: 该参数必须为NULL或空字符串。
lpUserName
[in] 指向一个以空字符结尾的字符串，该字符串指定用于进行连接的用户名。
如果lpUserName为NULL，则该函数使用默认的用户名。 （该进程的用户上下文提供了默认的用户名。）
当用户想要连接到已为其分配用户名或帐户以外的默认用户名或帐户的网络资源时，指定lpUserName参数。
用户名字符串表示安全上下文。 它可能特定于网络提供商。
Windows 95/98/Me: 该参数必须为NULL或空字符串。
dwFlags
[in] 指定描述连接选项的DWORD值。 目前定义了以下值。
值 含义 CONNECT_INTERACTIVE 如果设置了此标志，则操作系统可能会与用户进行交互以进行身份验证。 CONNECT_PROMPT 此标志指示系统不要为用户名或密码使用任何默认设置，也不会为用户提供替代方案。 除非CONNECT_INTERACTIVE也被设置，否则该标志被忽略。 CONNECT_REDIRECT 在进行连接时，该标志强制本地设备重定向。 如果NETRESOURCE的lpLocalName成员指定要重定向的本地设备，则此标志无效，因为操作系统仍尝试重定向指定的设备。 当操作系统自动选择本地设备时，lpAccessName参数必须指向返回缓冲区，并且dwType成员不能等于RESOURCETYPE_ANY。
如果未设置此标志，则只有在网络要求本地设备重定向时，才会自动选择本地设备进行重定向。
Windows XP: 当系统自动分配网络驱动器号时，分配以Z:,然后以Y:开始并以C:结尾的字母。 这可以减少每个登录驱动器号（例如网络驱动器号）与全局驱动器号（例如磁盘驱动器）之间的冲突。 请注意，以前的版本分配了以C开头的驱动器号，并以Z:结尾。
CONNECT_UPDATE_PROFILE 应记住网络资源连接。 如果设置了该位标志，则操作系统会在用户登录时自动尝试恢复连接。
操作系统只会记住重定向本地设备的成功连接。 它不记得不成功或无设备连接的连接。 （当lpLocalName成员为NULL或指向空字符串时，发生无设备连接。）
如果该位标志清除，则操作系统在登录时不会自动恢复连接。
CONNECT_COMMANDLINE Windows XP: 如果设置了此标志，操作系统将使用命令行而不是图形用户界面（GUI）提示用户进行认证。 除非CONNECT_INTERACTIVE也被设置，否则该标志被忽略。 CONNECT_CMD_SAVECRED Windows XP: 如果设置了此标志，并且操作系统提示输入凭证，则应由凭证管理器保存凭证。 如果凭据管理器在主叫方的登录会话中被禁用，或者网络提供商不支持保存凭据，则忽略此标志。 除非设置了CONNECT_COMMANDLINE标志，否则该标志也将被忽略。
返回值
如果函数成功，则返回值为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函数。 主要区别在于WNetUseConnection可以自动选择一个未使用的本地设备重定向到网络资源。
Windows XP: WNet函数创建和删除与登录会话相关联的MS-DOS设备名称空间中的网络驱动器号，因为MS-DOS设备由AuthenticationID标识。 （AuthenticationID是与登录会话关联的LUID。） 这可能会影响调用其中一个WNet函数的应用程序在一次用户登录下创建网络驱动器盘符，但会查询其他用户登录下的现有网络驱动器盘符。 这种情况的一个示例可能是用户的第二次登录在登录会话中创建的，例如，通过调用CreateProcessAsUser函数，并且第二次登录运行调用GetLogicalDrives函数的应用程序。 GetLogicalDrives在首次登录时不返回由WNet功能创建的网络驱动器号。 请注意，在前面的示例中，第一个登录会话仍然存在，并且该示例可以应用于任何登录会话，包括终端服务会话。 有关更多信息，请参阅MS-DOS设备名称。
Windows 95/98/Me: WNetAddConnection3W由Microsoft层为Unicode支持。 要使用它，必须将某些文件添加到应用程序中，如Windows 95/98 / Me系统上的Microsoft Layer for Unicode所述。
要求
Windows NT/2000/XP: 包含在Windows NT 3.1和更高版本中。
Windows 95/98/Me: 包含在Windows 95和更高版本中。
Header: 声明于 Winnetwk.h.
Library: 使用 Mpr.lib.
Unicode: 在Windows NT/2000/XP上作为Unicode和ANSI版本实现。 Microsoft层还支持Unicode。