WNetGetConnectionW 函数 (winnetwk.h)

项目
03/04/2024

WNetGetConnection 函数检索与本地设备关联的网络资源的名称。

语法

DWORD WNetGetConnectionW(
  [in]      LPCWSTR lpLocalName,
  [out]     LPWSTR  lpRemoteName,
  [in, out] LPDWORD lpnLength
);

参数

[in] lpLocalName

指向以 null 结尾的常量字符串的指针，该字符串指定要获取其网络名称的本地设备的名称。

[out] lpRemoteName

指向以 null 结尾的字符串的指针，该字符串接收用于建立连接的远程名称。

[in, out] lpnLength

指向变量的指针，该变量指定 lpRemoteName 参数指向的缓冲区的大小（以字符为单位）。如果函数因缓冲区不够大而失败，则此参数返回所需的缓冲区大小。

返回值

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

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

返回代码	说明
ERROR_BAD_DEVICE	lpLocalName 参数指向的字符串无效。
ERROR_NOT_CONNECTED	lpLocalName 指定的设备不是重定向的设备。有关更多信息，请参见下面的“备注”部分。
ERROR_MORE_DATA	缓冲区太小。 lpnLength 参数指向包含所需缓冲区大小的变量。后续调用中有更多条目可用。
ERROR_CONNECTION_UNAVAIL	设备当前未连接，但它是永久性连接。有关更多信息，请参见下面的“备注”部分。
ERROR_NO_NETWORK	网络不可用。
ERROR_EXTENDED_ERROR	发生特定于网络的错误。若要获取错误的说明，请调用 WNetGetLastError 函数。
ERROR_NO_NET_OR_BAD_PATH	没有一个提供程序将本地名称识别为具有连接。但是，该网络不适用于该连接可能所属的至少一个提供程序。

注解

如果网络连接是使用 Microsoft LAN Manager 网络建立的，并且调用应用程序在与建立连接的应用程序不同的登录会话中运行，则对关联本地设备的 WNetGetConnection 函数的调用将失败。函数失败并出现ERROR_NOT_CONNECTED或ERROR_CONNECTION_UNAVAIL。这是因为使用 Microsoft LAN Manager 建立的连接仅对与建立连接的应用程序在同一登录会话中运行的应用程序可见。 (若要防止对 WNetGetConnection 的调用失败，应用程序不足以在创建 connection 的用户帐户中运行。)

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

示例

有关演示如何使用 WNetGetConnection 函数检索与本地设备关联的网络资源名称的代码示例，请参阅检索连接名称。

注意

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

要求

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