Windows API函数之WNetAddConnection2

1.2.WNetAddConnection2函数
（1）函数的概述：
WNetAddConnection2 是一个Windows API函数，用于建立与网络资源（如网络驱动器或共享文件夹）的连接。与WNetAddConnection相比，WNetAddConnection2提供了更多的功能和灵活性，包括支持长文件名和Unicode字符串。它允许应用程序或用户访问网络资源，并将连接存储在Windows的网络连接列表中。

（2）函数所在的动态链接库：
WNetAddConnection2 函数位于 Mpr.dll 动态链接库中。

（3）函数的原型（C语言）：

DWORD WNetAddConnection2(  
  LPNETRESOURCE2 lpNetResource,  
  LPCWSTR       lpPassword,  
  LPCWSTR       lpUserName,  
  DWORD         dwFlags,  
  LPDWORD       lpLocalName  
);

（4）各参数及返回值的详细解释：

• lpNetResource：指向NETRESOURCE2结构的指针，该结构包含了要添加的网络连接的信息，如资源类型、远程网络名、本地设备名等。
• lpPassword：连接所需的密码。如果不需要密码，则为NULL。
• lpUserName：连接所需的用户名。如果不需要用户名或使用当前登录用户，则为NULL。
• dwFlags：控制函数行为的标志。常见的标志包括CONNECT_UPDATE_PROFILE（将连接信息更新到用户的网络连接配置文件中）和CONNECT_TEMPORARY（创建一个临时连接，不保存到配置文件中）。
• lpLocalName：一个指向DWORD的指针，该DWORD接收本地设备名的长度。如果不需要本地设备名，则此参数可以为NULL。

返回值：

• 如果函数成功执行，返回NO_ERROR（值为0）。
• 如果函数失败，返回非零错误码，可以使用FormatMessage函数获取详细的错误信息。

（5）函数的详细作用：
WNetAddConnection2的主要作用是创建一个新的网络连接，并将它添加到Windows的网络连接列表中。它根据提供的NETRESOURCE2结构中的信息尝试与指定的网络资源建立连接。一旦连接成功，应用程序和其他用户就可以通过Windows资源管理器或其他网络工具访问该资源。

（6）函数的C++示例：

#include <windows.h>  
#include <winnetwk.h>  
#include <iostream>  
  
int main() {  
    NETRESOURCE2 nr2;  
    DWORD dwFlags = CONNECT_UPDATE_PROFILE;  
    DWORD result;  
  
    ZeroMemory(&nr2, sizeof(nr2));  
    nr2.dwType = RESOURCETYPE_DISK;  
    nr2.dwScope = RESOURCE_GLOBALNET;  
    nr2.dwDisplayType = RESOURCEDISPLAYTYPE_GENERIC;  
    nr2.dwUsage = RESOURCEUSAGE_CONNECTABLE;  
    nr2.lpLocalName = NULL;  
    nr2.lpRemoteName = L"\\\\ServerName\\SharedFolder";  
    nr2.lpProvider = NULL;  
  
    result = WNetAddConnection2(&nr2, NULL, NULL, dwFlags, NULL);  
    if (result != NO_ERROR) {  
        std::cerr << "Failed to add connection: " << result << std::endl;  
        return 1;  
    }  
  
    std::cout << "Connection added successfully." << std::endl;  
    return 0;  
}

请注意，在编译时，需要链接Mpr.lib库。

（7）使用时的注意事项：

• 确保目标网络资源是存在的，并且你有适当的权限进行连接。
• 如果应用程序在多线程环境中运行，需要确保对网络连接的操作是线程安全的。
• 在不再需要网络连接时，应该使用WNetCancelConnection2函数来断开连接。
• 考虑到兼容性和安全性，建议查阅最新的Windows API文档，以获取关于WNetAddConnection2函数及其替代品的最新信息和建议。
• 在处理密码时，应确保密码的安全性，避免明文存储或传输。
• 当使用Unicode字符串时，确保你的代码和库文件都是支持Unicode的，以防止编码问题。