WNetAddConnection2功能连接到网络资源。该函数可以将本地设备重定向到网络资源。
WNetAddConnection2功能取代WNetAddConnection功能。如果您将一个句柄传递给网络资源提供者可以用作对话框的所有者窗口的窗口,请使用WNetAddConnection3函数。
DWORD WNetAddConnection2(
LPNETRESOURCE 【lpNetResource】, | //指向结构,指定连接细节 |
LPCTSTR 【//指向密码字符串的指针】, | //指向密码字符串 |
LPCTSTR 【lpUsername】, | //指向用户名字符串 |
DWORD 【dwFlags中】 | //指定连接选项的位标志集 |
); |
参数
【lpNetResource】
指向NETRESOURCE结构,指定建议连接的详细信息:有关网络资源,本地设备和网络资源提供程序的信息。
您必须指定NETRESOURCE结构的以下成员:
会员 | 描述 |
dwType | 指定要连接的网络资源的类型。如果lpLocalName指向一个非空字符串,则此成员可以是RESOURCETYPE_DISK或RESOURCETYPE_PRINT。如果lpLocalName为NULL或指向空字符串,则dwType可以是RESOURCETYPE_DISK,RESOURCETYPE_PRINT或RESOURCETYPE_ANY。 |
lpLocalName | 指向指定要重定向的本地设备的名称的空终止字符串,例如“F:”或“LPT1”。字符串以不区分大小写的方式处理。如果字符串为空或lpLocalName为NULL,则该函数将连接到网络资源而不重定向本地设备。 |
lpRemoteName | 指向指定要连接到的网络资源的以空字符结尾的字符串。字符串的长度可以达到MAX_PATH个字符。字符串必须遵循网络提供商的命名约定。 |
lpProvider | 指向指定要连接的网络提供商的以空值终止的字符串。如果lpProvider为NULL或指向空字符串,则操作系统将通过解析lpRemoteName指向的字符串来尝试确定正确的提供程序。 |
只有当您确定要使用哪个网络提供商时,才应该设置此成员。否则,让操作系统确定网络名称映射到哪个提供商。 | |
如果此成员不为NULL,则操作系统将尝试仅连接到指定的网络提供商。 |
WNetAddConnection2函数忽略NETRESOURCE结构的其他成员。
【//指向密码字符串的指针】
指向以空字符结尾的字符串,指定要在进行网络连接时使用的密码。
如果【//指向密码字符串的指针】为NULL,则该函数使用与【lpUserName.】指定的用户相关联的当前默认密码
如果【//指向密码字符串的指针】指向空字符串,则该函数不使用密码。
【lpUsername】
指向一个以null结尾的字符串,指定用于进行连接的用户名。
如果【lpUserName】为NULL,则该函数使用默认用户名。该进程的用户上下文提供了默认的用户名。
当用户想要连接到已为其分配了除默认用户名或帐户之外的用户名或帐户的网络资源时,将指定【lpUserName】参数。
用户名字符串表示安全上下文。它可能是一个网络提供商。
【dwFlags中】
一组指定连接选项的位标志。当前定义了以下位标志常量:
值 | 含义 |
CONNECT_UPDATE_PROFILE | 应该记住网络资源连接。 如果设置了该位标志,则当用户登录时,操作系统会自动尝试恢复连接。 操作系统只记录重定向本地设备的成功连接。它不记得连接失败或无法连接。当lpLocalName为NULL或指向空字符串时,就会发生无形连接。 如果该位标志清除,操作系统将不会在登录时自动恢复连接。 |
返回值
如果函数成功,返回值为NO_ERROR。
如果函数失败,则返回值是错误代码。返回错误代码可以与Windows 3.1功能WNetAddConnection的行为兼容。您还可以调用GetLastError函数获取(相同)错误代码。当WNetAddConnection2失败时,可能会返回以下错误代码之一:
值 | 含义 |
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 | 指定的密码无效。 |
ERROR_NO_NET_OR_BAD_PATH | 网络组件尚未启动,或指定的名称无法处理。 |
ERROR_NO_NETWORK | 没有网络存在。 |
也可以看看
WNetAddConnection, WNetAddConnection3, WNetCancelConnection2, WNetGetConnection, WNetGetLastError, NETRESOURCE