Função WlanGetProfile (wlanapi.h)
A função WlanGetProfile recupera todas as informações sobre um perfil sem fio especificado.
Sintaxe
DWORD WlanGetProfile(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[in] LPCWSTR strProfileName,
[in] PVOID pReserved,
[out] LPWSTR *pstrProfileXml,
[in, out, optional] DWORD *pdwFlags,
[out, optional] DWORD *pdwGrantedAccess
);
Parâmetros
[in] hClientHandle
O identificador de sessão do cliente, obtido por uma chamada anterior para a função WlanOpenHandle .
[in] pInterfaceGuid
O GUID da interface sem fio.
Uma lista dos GUIDs para interfaces sem fio no computador local pode ser recuperada usando a função WlanEnumInterfaces .
[in] strProfileName
O nome do perfil. Os nomes de perfil diferenciam maiúsculas de minúsculas. Essa cadeia de caracteres deve ser terminada em NULL. O comprimento máximo do nome do perfil é de 255 caracteres. Isso significa que o comprimento máximo dessa cadeia de caracteres, incluindo o terminador NULL, é de 256 caracteres.
Windows XP com SP3 e API lan sem fio para Windows XP com SP2: O nome do perfil é derivado automaticamente do SSID da rede. Para perfis de rede de infraestrutura, o nome do perfil é o SSID da rede. Para perfis de rede ad hoc, o nome do perfil é o SSID da rede ad hoc seguido por -adhoc.
[in] pReserved
Reservado para uso futuro. Deve ser definido como NULL.
[out] pstrProfileXml
Uma cadeia de caracteres que é a representação XML do perfil consultado. Não há nenhum comprimento de cadeia de caracteres máximo predefinido.
[in, out, optional] pdwFlags
Na entrada, um ponteiro para o local do endereço usado para fornecer informações adicionais sobre a solicitação. Se esse parâmetro for NULL na entrada, nenhuma informação sobre sinalizadores de perfil será retornada. Na saída, um ponteiro para o local do endereço usado para receber sinalizadores de perfil.
Windows XP com SP3 e API lan sem fio para Windows XP com SP2: Não há suporte para perfis por usuário. Defina esse parâmetro como NULL.
O parâmetro pdwFlags pode apontar para um local de endereço que contém os seguintes valores:
| Valor | Significado |
|---|---|
|
Na entrada, esse sinalizador indica que o chamador deseja recuperar a chave de texto sem formatação de um perfil sem fio. Se o thread de chamada tiver as permissões necessárias, a função WlanGetProfile retornará a chave de texto sem formatação no elemento keyMaterial do perfil retornado no buffer apontado pelo parâmetro pstrProfileXml .
Para que a chamada WlanGetProfile retorne a chave de texto sem formatação, as permissões de wlan_secure_get_plaintext_key do tipo enumerado WLAN_SECURABLE_OBJECT devem ser definidas no thread de chamada. A DACL também deve conter uma ACE que conceda permissão WLAN_READ_ACCESS ao token de acesso do thread de chamada. Por padrão, as permissões para recuperar a chave de texto sem formatação são permitidas somente para os membros do grupo Administradores em um computador local. Se o thread de chamada não tiver as permissões necessárias, a função WlanGetProfile retornará a chave criptografada no elemento keyMaterial do perfil retornado no buffer apontado pelo parâmetro pstrProfileXml . Nenhum erro será retornado se o thread de chamada não tiver as permissões necessárias. Windows 7: Esse sinalizador passado na entrada é uma extensão para APIs sem fio nativas adicionadas no Windows 7 e posterior. O parâmetro pdwFlags é um parâmetro __inout_opt no Windows 7 e posterior. |
|
Na saída quando a chamada WlanGetProfile for bem-sucedida, esse sinalizador indica que esse perfil foi criado pela política de grupo. Um perfil de política de grupo é somente leitura. Nem o conteúdo nem a ordem de preferência do perfil podem ser alterados. |
|
Na saída quando a chamada WlanGetProfile for bem-sucedida, esse sinalizador indica que o perfil é um perfil de usuário para o usuário específico em cujo contexto reside o thread de chamada. Se não estiver definido, esse perfil será um perfil de todos os usuários. |
[out, optional] pdwGrantedAccess
A máscara de acesso do perfil de todos os usuários.
| Valor | Significado |
|---|---|
|
O usuário pode exibir o conteúdo do perfil. |
|
O usuário tem acesso de leitura e o usuário também pode se conectar e desconectar de uma rede usando o perfil. Se um usuário tiver WLAN_EXECUTE_ACCESS, o usuário também terá WLAN_READ_ACCESS. |
|
O usuário tem acesso de execução e o usuário também pode modificar o conteúdo do perfil ou excluir o perfil. Se um usuário tiver WLAN_WRITE_ACCESS, o usuário também terá WLAN_EXECUTE_ACCESS e WLAN_READ_ACCESS. |
Retornar valor
Se a função obtiver êxito, o valor retornado será ERROR_SUCCESS.
Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de retorno.
| Código de retorno | Descrição |
|---|---|
|
O chamador não tem permissões suficientes. Esse erro será retornado se o parâmetro pstrProfileXml especificar um perfil de todos os usuários, mas o chamador não tiver acesso de leitura no perfil. |
|
Um identificador é inválido. Esse erro será retornado se o identificador especificado no parâmetro hClientHandle não tiver sido encontrado na tabela de identificadores. |
|
Um parâmetro está incorreto. Esse erro será retornado se qualquer uma das seguintes condições ocorrer:
|
|
Não há armazenamento suficiente disponível para processar esse comando. Esse erro será retornado se o sistema não puder alocar memória para o perfil. |
|
O perfil especificado por strProfileName não foi encontrado. |
|
Vários RPC e outros códigos de erro. Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Comentários
Se a função WlanGetProfile for bem-sucedida, o perfil sem fio será retornado no buffer apontado pelo parâmetro pstrProfileXml . O buffer contém uma cadeia de caracteres que é a representação XML do perfil consultado. Para obter uma descrição da representação XML do perfil sem fio, consulte WLAN_profile Esquema.
O chamador é responsável por chamar a função WlanFreeMemory para liberar a memória alocada para o ponteiro de buffer para pelo parâmetro pstrProfileXml quando o buffer não for mais necessário.
Se pstrProfileXml especificar um perfil de todos os usuários, o chamador WlanGetProfile deverá ter acesso de leitura no perfil. Caso contrário, a chamada WlanGetProfile falhará com um valor retornado de ERROR_ACCESS_DENIED. As permissões em um perfil de todos os usuários são estabelecidas quando o perfil é criado ou salvo usando WlanSetProfile ou WlanSaveTemporaryProfile.
Windows 7:
O elemento keyMaterial retornado no esquema de perfil apontado pelo pstrProfileXml poderá ser solicitado como texto não criptografado se a função WlanGetProfile for chamada com o sinalizador WLAN_PROFILE_GET_PLAINTEXT_KEY definido no valor apontado pelo parâmetro pdwFlags na entrada.
Para uma chave WEP, 5 caracteres ASCII ou 10 caracteres hexadecimal podem ser usados para definir a chave de texto não criptografado quando o perfil é criado ou atualizado. No entanto, um perfil WEP será salvo com 10 caracteres hexadecimais na chave, independentemente de qual entrada original tenha sido usada para criar o perfil. Portanto, no perfil retornado pela função WlanGetProfile , a chave WEP de texto não criptografado sempre é retornada como 10 caracteres hexadecimal.
Para que a chamada WlanGetProfile retorne a chave de texto sem formatação, as permissões de wlan_secure_get_plaintext_key do tipo enumerado WLAN_SECURABLE_OBJECT devem ser definidas no thread de chamada. A DACL também deve conter uma ACE que conceda permissão WLAN_READ_ACCESS ao token de acesso do thread de chamada. Por padrão, as permissões para recuperar a chave de texto sem formatação são permitidas somente para os membros do grupo Administradores em um computador local.
Se o thread de chamada não tiver as permissões necessárias, a função WlanGetProfile retornará a chave criptografada no elemento keyMaterial do perfil retornado no buffer apontado pelo parâmetro pstrProfileXml . Nenhum erro será retornado se o thread de chamada não tiver as permissões necessárias.
Por padrão, o elemento keyMaterial retornado no perfil apontado pelo pstrProfileXml é criptografado. Se o processo for executado no contexto da conta LocalSystem no mesmo computador, você poderá descriptografar o material de chave chamando a função CryptUnprotectData .
Windows Server 2008 e Windows Vista: O elemento keyMaterial retornado no esquema de perfil apontado pelo pstrProfileXml é sempre criptografado. Se o processo for executado no contexto da conta LocalSystem, você poderá descriptografar o material de chave chamando a função CryptUnprotectData .
Windows XP com SP3 e API lan sem fio para Windows XP com SP2: O material da chave nunca é criptografado.
Exemplos
O exemplo a seguir enumera as interfaces LAN sem fio no computador local, recupera informações para um perfil sem fio específico em cada interface lan sem fio e imprime os valores recuperados. A cadeia de caracteres que é a representação XML do perfil consultado também é impressa.
#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;
LPWSTR pProfileXml = NULL;
DWORD dwFlags = 0;
DWORD dwGrantedAccess = 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"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\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\n");
dwResult = WlanGetProfile(hClient,
&pIfInfo->InterfaceGuid,
pProfileName,
NULL,
&pProfileXml,
&dwFlags,
&dwGrantedAccess);
if (dwResult != ERROR_SUCCESS) {
wprintf(L"WlanGetProfile 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" Profile XML string:\n");
wprintf(L"%ws\n\n", pProfileXml);
wprintf(L" dwFlags:\t 0x%x", dwFlags);
// if (dwFlags & WLAN_PROFILE_GET_PLAINTEXT_KEY)
// wprintf(L" Get Plain Text Key");
if (dwFlags & WLAN_PROFILE_GROUP_POLICY)
wprintf(L" Group Policy");
if (dwFlags & WLAN_PROFILE_USER)
wprintf(L" Per User Profile");
wprintf(L"\n");
wprintf(L" dwGrantedAccess: 0x%x", dwGrantedAccess);
if (dwGrantedAccess & WLAN_READ_ACCESS)
wprintf(L" Read access");
if (dwGrantedAccess & WLAN_EXECUTE_ACCESS)
wprintf(L" Execute access");
if (dwGrantedAccess & WLAN_WRITE_ACCESS)
wprintf(L" Write access");
wprintf(L"\n");
wprintf(L"\n");
}
}
}
if (pProfileXml != NULL) {
WlanFreeMemory(pProfileXml);
pProfileXml = NULL;
}
if (pIfList != NULL) {
WlanFreeMemory(pIfList);
pIfList = NULL;
}
return dwRetVal;
}
Requisitos
| Cliente mínimo com suporte | Windows Vista, Windows XP com SP3 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | wlanapi.h (inclua Wlanapi.h) |
| Biblioteca | Wlanapi.lib |
| DLL | Wlanapi.dll |
| Redistribuível | API de LAN sem fio para Windows XP com SP2 |