wlanGetProfileCustomUserData 函数 (wlanapi.h)

项目
03/04/2024

WlanGetProfileCustomUserData 函数获取与无线配置文件关联的自定义用户数据。

语法

DWORD WlanGetProfileCustomUserData(
  [in]  HANDLE     hClientHandle,
  [in]  const GUID *pInterfaceGuid,
  [in]  LPCWSTR    strProfileName,
        PVOID      pReserved,
  [out] DWORD      *pdwDataSize,
  [out] PBYTE      *ppData
);

参数

[in] hClientHandle

客户端的会话句柄，由上一次对 WlanOpenHandle 函数的调用获取。

[in] pInterfaceGuid

指向无线 LAN 接口 GUID 的指针。

[in] strProfileName

与自定义用户数据关联的配置文件的名称。配置文件名称区分大小写。此字符串必须以 NULL 结尾。

pReserved

保留供将来使用。必须设置为 NULL。

[out] pdwDataSize

ppData 参数指向的用户数据缓冲区的大小（以字节为单位）。

[out] ppData

用户数据的指针。

返回值

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

如果函数失败，则返回值可能是以下返回代码之一。

返回代码	说明
ERROR_FILE_NOT_FOUND	系统找不到指定的文件。如果指定的配置文件不存在用户自定义数据，则返回此错误。
ERROR_INVALID_PARAMETER	hClientHandle 参数为 NULL 或无效，pInterfaceGuid 参数为 NULL，strProfileName 参数为 NULL，pReserved 参数不为 NULL，pdwDataSize 参数为 0 或 ppData 参数为 NULL。
ERROR_FILE_NOT_FOUND	系统找不到指定的文件。如果指定的配置文件不存在任何自定义用户数据，则返回此错误。
ERROR_INVALID_HANDLE	在句柄表中找不到句柄 hClientHandle 。
ERROR_NOT_SUPPORTED	此函数是从不受支持的平台调用的。如果从具有 SP3 的 Windows XP 或具有 SP2 客户端的 Windows XP 无线 LAN API 调用此函数，则将返回此值。
RPC_STATUS	各种错误代码。

注解

对于 Native Wifi AutoConfig 服务使用的每个无线 WLAN 配置文件，Windows 维护自定义用户数据的概念。此自定义用户数据最初不存在，但可以通过调用 WlanSetProfileCustomUserData 函数进行设置。每当通过调用 WlanSetProfile 函数修改配置文件时，自定义用户数据都会重置为空。

设置自定义用户数据后，可以使用 WlanGetProfileCustomUserData 函数访问此数据。

调用方负责使用 WlanFreeMemory 函数释放为 ppData 参数指向的缓冲区分配的内存。

示例

以下示例枚举本地计算机上的无线 LAN 接口，然后尝试检索每个无线 LAN 接口上特定无线配置文件的任何自定义用户数据信息。打印用户自定义数据的大小。

注意如果未安装并启动无线 LAN 服务，本示例将无法在 Windows Server 2008 和 Windows Server 2008 R2 上加载。

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <wlanapi.h>
#include <objbase.h>
#include <wtypes.h>

#include <stdio.h>
#include <stdlib.h>

// Need to link with Wlanapi.lib and Ole32.lib
#pragma comment(lib, "wlanapi.lib")
#pragma comment(lib, "ole32.lib")


int _cdecl wmain(int argc, WCHAR **argv)
{

    // Declare and initialize variables.

    HANDLE hClient = NULL;
    DWORD dwMaxClient = 2;      //    
    DWORD dwCurVersion = 0;
    DWORD dwResult = 0;
    DWORD dwRetVal = 0;
    int iRet = 0;
    
    WCHAR GuidString[39] = {0};

    unsigned int i;

    /* variables used for WlanEnumInterfaces  */

    PWLAN_INTERFACE_INFO_LIST pIfList = NULL;
    PWLAN_INTERFACE_INFO pIfInfo = NULL;

    LPCWSTR pProfileName = NULL;

    PBYTE pProfileData = NULL;
    DWORD dwDataSize = 0;
   
        // Validate the parameters
    if (argc < 2) {
        wprintf(L"usage: %s <profile>\n", argv[0]);
        wprintf(L"   Gets a wireless profile\n");
        wprintf(L"   Example\n");
        wprintf(L"       %s \"Default Wireless\"\n", argv[0]);
        exit(1);
    }
    
    pProfileName = argv[1];
     
    wprintf(L"Custom user data information for profile: %ws\n\n", pProfileName);
    
    dwResult = WlanOpenHandle(dwMaxClient, NULL, &dwCurVersion, &hClient);
    if (dwResult != ERROR_SUCCESS) {
        wprintf(L"WlanOpenHandle failed with error: %u\n", dwResult);
        return 1;
        // You can use FormatMessage here to find out why the function failed
    }

    dwResult = WlanEnumInterfaces(hClient, NULL, &pIfList);
    if (dwResult != ERROR_SUCCESS) {
        wprintf(L"WlanEnumInterfaces failed with error: %u\n", dwResult);
        return 1;
        // You can use FormatMessage here to find out why the function failed
    } else {
        wprintf(L"WLAN_INTERFACE_INFO_LIST for this system\n");

        wprintf(L"Num Entries: %lu\n", pIfList->dwNumberOfItems);
        wprintf(L"Current Index: %lu\n", pIfList->dwIndex);
        for (i = 0; i < (int) pIfList->dwNumberOfItems; i++) {
            pIfInfo = (WLAN_INTERFACE_INFO *) &pIfList->InterfaceInfo[i];
            wprintf(L"  Interface Index[%u]:\t %lu\n", i, i);
            iRet = StringFromGUID2(pIfInfo->InterfaceGuid, (LPOLESTR) &GuidString, 
                sizeof(GuidString)/sizeof(*GuidString)); 
            // For c rather than C++ source code, the above line needs to be
            // iRet = StringFromGUID2(&pIfInfo->InterfaceGuid, (LPOLESTR) &GuidString, 
            //     sizeof(GuidString)/sizeof(*GuidString)); 
            if (iRet == 0)
                wprintf(L"StringFromGUID2 failed\n");
            else {
                wprintf(L"  InterfaceGUID[%d]: %ws\n",i, GuidString);
            }    
            wprintf(L"  Interface Description[%d]: %ws", i, 
                pIfInfo->strInterfaceDescription);
            wprintf(L"\n");
            wprintf(L"  Interface State[%d]:\t ", i);
            switch (pIfInfo->isState) {
            case wlan_interface_state_not_ready:
                wprintf(L"Not ready\n");
                break;
            case wlan_interface_state_connected:
                wprintf(L"Connected\n");
                break;
            case wlan_interface_state_ad_hoc_network_formed:
                wprintf(L"First node in a ad hoc network\n");
                break;
            case wlan_interface_state_disconnecting:
                wprintf(L"Disconnecting\n");
                break;
            case wlan_interface_state_disconnected:
                wprintf(L"Not connected\n");
                break;
            case wlan_interface_state_associating:
                wprintf(L"Attempting to associate with a network\n");
                break;
            case wlan_interface_state_discovering:
                wprintf(L"Auto configuration is discovering settings for the network\n");
                break;
            case wlan_interface_state_authenticating:
                wprintf(L"In process of authenticating\n");
                break;
            default:
                wprintf(L"Unknown state %ld\n", pIfInfo->isState);
                break;
            }
            wprintf(L"\n");

            dwResult = WlanGetProfileCustomUserData(hClient,
                                             &pIfInfo->InterfaceGuid,
                                             pProfileName,
                                             NULL,
                                             &dwDataSize,
                                             &pProfileData);

            if (dwResult != ERROR_SUCCESS) {
                wprintf(L"WlanGetProfileCustomData failed with error: %u\n",
                        dwResult);
                // You can use FormatMessage to find out why the function failed
            } else {
                wprintf(L"Profile Name:  %ws\n", pProfileName);

                wprintf(L"  dwDataSize:\t    0x%x\n", dwDataSize);
                wprintf(L"  Profile Custom Data:\n");
//                wprintf(L"%ws\n\n", pProfileXml);

                wprintf(L"\n");    

                wprintf(L"\n");
            }
        }

    }
    if (pProfileData != NULL) {
        WlanFreeMemory(pProfileData);
        pProfileData = NULL;
    }

    if (pIfList != NULL) {
        WlanFreeMemory(pIfList);
        pIfList = NULL;
    }

    return dwRetVal;
}

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	wlanapi.h (包括 Wlanapi.h)
Library	Wlanapi.lib
DLL	Wlanapi.dll

另请参阅

WlanGetProfile

WlanGetProfileList

WlanSetProfile

WlanSetProfileCustomUserData

通过

wlanGetProfileCustomUserData 函数 (wlanapi.h)

语法

参数

返回值

注解

示例

要求

另请参阅

反馈

其他资源