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。

如果函式失敗，傳回值可能是下列其中一個傳回碼。

傳回碼	Description
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或Windows XP搭配SP2用戶端的無線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)
程式庫	Wlanapi.lib
Dll	Wlanapi.dll

另請參閱

WlanGetProfile

WlanGetProfileList

WlanSetProfile

WlanSetProfileCustomUserData

共用方式為

WlanGetProfileCustomUserData 函式 (wlanapi.h)

語法

參數

傳回值

備註

範例

規格需求

另請參閱

意見反應

其他資源