通过

WNetUseConnectionA 函数 (winnetwk.h)

  • 项目

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

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

语法

DWORD WNetUseConnectionA(
  [in]      HWND           hwndOwner,
  [in]      LPNETRESOURCEA lpNetResource,
  [in]      LPCSTR         lpPassword,
  [in]      LPCSTR         lpUserId,
  [in]      DWORD          dwFlags,
  [out]     LPSTR          lpAccessName,
  [in, out] LPDWORD        lpBufferSize,
  [out]     LPDWORD        lpResult
);

参数

[in] hwndOwner

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

[in] lpNetResource

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

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

成员 含义
dwType
 指定要连接到的资源的类型。

在此成员中指定资源类型（例如RESOURCETYPE_DISK或RESOURCETYPE_PRINT）最有效。 但是，如果 lpLocalName 成员为 NULL，或者它指向空字符串且未设置CONNECT_REDIRECT，则可以RESOURCETYPE_ANY dwType 。

仅当函数不自动选择要重定向到网络资源的设备时，此方法才有效。

尽管此成员是必需的，但网络服务提供商可能会忽略其信息。
lpLocalName
 指向以 null 结尾的字符串的指针，该字符串指定要重定向的本地设备的名称，例如“F：”或“LPT1”。 字符串以不区分大小写的方式进行处理。

如果字符串为空，或者 lpLocalName 为 NULL，则无需重定向即可连接到网络。

如果在 dwFlags 参数中设置了CONNECT_REDIRECT值，或者网络需要重定向的本地设备，则函数将选择要重定向的本地设备，并在 lpAccessName 参数中返回设备的名称。
lpRemoteName
 指向以 null 结尾的字符串的指针，该字符串指定要连接到的网络资源。 字符串的长度最多可以MAX_PATH个字符，并且必须遵循网络提供商的命名约定。
lpProvider
 指向以 null 结尾的字符串的指针，该字符串指定要连接到的网络提供程序。 如果 lpProvider 为 NULL，或者如果它指向空字符串，则操作系统会尝试通过分析 lpRemoteName 成员指向的字符串来确定正确的提供程序。

如果此成员不为 NULL，则操作系统将尝试仅与命名的网络提供程序建立连接。

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

WNetUseConnection 函数忽略 NETRESOURCE 结构的其他成员。 有关详细信息，请参阅以下 dwFlags 参数的说明。

[in] lpPassword

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

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

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

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

[in] lpUserId

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

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

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

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

[in] dwFlags

描述连接的位标志集。 此参数可以是以下值的任意组合。

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

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

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

Windowsxp： 当系统自动分配网络驱动器号时，将分配以 Z：开头的字母，然后以 Y：开头，以 C：结尾。 这可以减少每个登录驱动器号 (（例如网络驱动器号) ）与全局驱动器号 (（如磁盘驱动器) ）之间的冲突。 请注意，以前版本分配的驱动器号以 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： 不支持此值。

[out] lpAccessName

指向接收连接上的系统请求的缓冲区的指针。 此参数可以为 NULL。

如果指定了此参数，并且 NETRESOURCE 结构的 lpLocalName 成员指定了本地设备，则此缓冲区将接收本地设备名称。 如果 lpLocalName 未指定设备，并且网络需要本地设备重定向，或者如果设置了CONNECT_REDIRECT值，则此缓冲区将接收重定向的本地设备的名称。

否则，复制到缓冲区的名称是远程资源的名称。 如果指定，则此缓冲区的大小必须至少与 lpRemoteName 成员指向的字符串一样大。

[in, out] lpBufferSize

指向变量的指针，该变量指定 lpAccessName 缓冲区的大小（以字符为单位）。 如果调用因缓冲区不够大而失败，则函数将在此位置返回所需的缓冲区大小。 有关详细信息，请参阅返回值部分中 lpAccessName 参数的说明和ERROR_MORE_DATA错误代码。

[out] lpResult

指向接收有关连接的其他信息的变量的指针。 此参数可以是以下值。

值 含义
CONNECT_LOCALDRIVE
 如果设置了此标志，则连接是使用本地设备重定向建立的。 如果 lpAccessName 参数指向缓冲区，则会将本地设备名称复制到缓冲区。

返回值

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

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

返回代码 说明
ERROR_ACCESS_DENIED
 调用方无权访问网络资源。
ERROR_ALREADY_ASSIGNED
 lpLocalName 成员指定的本地设备已连接到网络资源。
ERROR_BAD_DEVICE
 lpLocalName 指定的值无效。
ERROR_BAD_NET_NAME
 任何网络资源提供程序都不接受 由 lpRemoteName 成员指定的值，因为资源名称无效，或者无法找到命名的资源。
ERROR_BAD_PROVIDER
 lpProvider 成员指定的值与任何提供程序都不匹配。
ERROR_CANCELLED
 用户通过某个网络资源提供程序中的对话框或被调用的资源取消了建立连接的尝试。
ERROR_EXTENDED_ERROR
 发生特定于网络的错误。 若要获取错误的说明，请调用 WNetGetLastError 函数。
ERROR_INVALID_ADDRESS
 调用方传入指向无法访问的缓冲区的指针。
ERROR_INVALID_PARAMETER
 此错误是由以下情况之一导致的：
  1. lpRemoteName 成员为 NULL。 此外， lpAccessName 不为 NULL，但 lpBufferSize 为 NULL 或指向零。
  2. dwType 成员既不是RESOURCETYPE_DISK也不是RESOURCETYPE_PRINT。 此外，CONNECT_REDIRECT在 dwFlags 中设置， lpLocalName 为 NULL，或者连接到需要重定向本地设备的网络。
ERROR_INVALID_PASSWORD
 指定的密码无效，并且未设置CONNECT_INTERACTIVE标志。
ERROR_MORE_DATA
 lpAccessName 缓冲区太小。

如果重定向了本地设备，则缓冲区需要足够大才能包含本地设备名称。 否则，缓冲区必须足够大，以包含 lpRemoteName 指向的字符串，或 lpRemoteName 指向其别名的可连接资源的名称。 如果返回此错误，则未建立任何连接。
ERROR_NO_MORE_ITEMS
 操作系统无法自动选择本地重定向，因为所有有效的本地设备都在使用中。
ERROR_NO_NET_OR_BAD_PATH
 操作无法完成，原因是网络组件未启动，或者无法识别指定的资源名称。
ERROR_NO_NETWORK
 网络不可用。

注解

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

注意

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

要求

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

另请参阅

WNetAddConnection2

WNetAddConnection3

WNetGetConnection

Windows 网络 (WNet) 概述

Windows 网络函数

WnetCancelConnection