Función WlanGetProfile (wlanapi.h)
La función WlanGetProfile recupera toda la información sobre un perfil inalámbrico especificado.
Sintaxis
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
Identificador de sesión del cliente, obtenido por una llamada anterior a la función WlanOpenHandle .
[in] pInterfaceGuid
GUID de la interfaz inalámbrica.
Se puede recuperar una lista de los GUID para interfaces inalámbricas en el equipo local mediante la función WlanEnumInterfaces .
[in] strProfileName
Nombre del perfil. Los nombres de perfil distinguen mayúsculas de minúsculas. Esta cadena debe terminar en NULL. La longitud máxima del nombre del perfil es de 255 caracteres. Esto significa que la longitud máxima de esta cadena, incluido el terminador NULL, es de 256 caracteres.
Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: El nombre del perfil se deriva automáticamente del SSID de la red. En el caso de los perfiles de red de infraestructura, el nombre del perfil es el SSID de la red. En el caso de los perfiles de red ad hoc, el nombre del perfil es el SSID de la red ad hoc seguido de -adhoc.
[in] pReserved
Reservado para uso futuro. Debe establecerse en NULL.
[out] pstrProfileXml
Cadena que es la representación XML del perfil consultado. No hay ninguna longitud de cadena máxima predefinida.
[in, out, optional] pdwFlags
En la entrada, un puntero a la ubicación de la dirección que se usa para proporcionar información adicional sobre la solicitud. Si este parámetro es NULL en la entrada, no se devolverá información sobre las marcas de perfil. En la salida, un puntero a la ubicación de la dirección que se usa para recibir marcas de perfil.
Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: No se admiten perfiles por usuario. Establezca este parámetro en NULL.
El parámetro pdwFlags puede apuntar a una ubicación de dirección que contiene los siguientes valores:
| Valor | Significado |
|---|---|
|
En la entrada, esta marca indica que el autor de la llamada quiere recuperar la clave de texto sin formato de un perfil inalámbrico. Si el subproceso de llamada tiene los permisos necesarios, la función WlanGetProfile devuelve la clave de texto sin formato en el elemento keyMaterial del perfil devuelto en el búfer al que apunta el parámetro pstrProfileXml .
Para que la llamada a WlanGetProfile devuelva la clave de texto sin formato, los permisos wlan_secure_get_plaintext_key del tipo enumerado WLAN_SECURABLE_OBJECT deben establecerse en el subproceso que llama. La DACL también debe contener una ACE que conceda permiso WLAN_READ_ACCESS al token de acceso del subproceso que realiza la llamada. De forma predeterminada, los permisos para recuperar la clave de texto sin formato solo se permiten a los miembros del grupo Administradores en un equipo local. Si el subproceso que realiza la llamada carece de los permisos necesarios, la función WlanGetProfile devuelve la clave cifrada en el elemento keyMaterial del perfil devuelto en el búfer al que apunta el parámetro pstrProfileXml . No se devuelve ningún error si el subproceso que realiza la llamada carece de los permisos necesarios. Windows 7: Esta marca pasada en la entrada es una extensión para las API inalámbricas nativas agregadas en Windows 7 y versiones posteriores. El parámetro pdwFlags es un parámetro __inout_opt en Windows 7 y versiones posteriores. |
|
En la salida cuando la llamada a WlanGetProfile se realiza correctamente, esta marca indica que este perfil se creó mediante la directiva de grupo. Un perfil de directiva de grupo es de solo lectura. Ni el contenido ni el orden de preferencia del perfil se pueden cambiar. |
|
En la salida cuando la llamada a WlanGetProfile se realiza correctamente, esta marca indica que el perfil es un perfil de usuario para el usuario específico en cuyo contexto reside el subproceso que realiza la llamada. Si no se establece, este perfil es un perfil de usuario completo. |
[out, optional] pdwGrantedAccess
Máscara de acceso del perfil de todos los usuarios.
| Valor | Significado |
|---|---|
|
El usuario puede ver el contenido del perfil. |
|
El usuario tiene acceso de lectura y el usuario también puede conectarse a una red y desconectarse de ella mediante el perfil. Si un usuario tiene WLAN_EXECUTE_ACCESS, el usuario también tiene WLAN_READ_ACCESS. |
|
El usuario tiene acceso de ejecución y el usuario también puede modificar el contenido del perfil o eliminar el perfil. Si un usuario tiene WLAN_WRITE_ACCESS, el usuario también tiene WLAN_EXECUTE_ACCESS y WLAN_READ_ACCESS. |
Valor devuelto
Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.
Si se produce un error en la función, el valor devuelto puede ser uno de los siguientes códigos de retorno.
| Código devuelto | Descripción |
|---|---|
|
El autor de la llamada no tiene permisos suficientes. Este error se devuelve si el parámetro pstrProfileXml especifica un perfil de usuario completo, pero el autor de la llamada no tiene acceso de lectura en el perfil. |
|
Un identificador no es válido. Este error se devuelve si no se encontró el identificador especificado en el parámetro hClientHandle en la tabla de identificadores. |
|
Un parámetro es incorrecto. Este error se devuelve si se produce alguna de las condiciones siguientes:
|
|
No hay suficiente almacenamiento disponible para procesar este comando. Este error se devuelve si el sistema no pudo asignar memoria para el perfil. |
|
No se encontró el perfil especificado por strProfileName . |
|
Varios rpc y otros códigos de error. Use FormatMessage para obtener la cadena de mensaje del error devuelto. |
Comentarios
Si la función WlanGetProfile se realiza correctamente, el perfil inalámbrico se devuelve en el búfer al que apunta el parámetro pstrProfileXml . El búfer contiene una cadena que es la representación XML del perfil consultado. Para obtener una descripción de la representación XML del perfil inalámbrico, consulta WLAN_profile Esquema.
El autor de la llamada es responsable de llamar a la función WlanFreeMemory para liberar la memoria asignada para el puntero de búfer a por el parámetro pstrProfileXml cuando el búfer ya no es necesario.
Si pstrProfileXml especifica un perfil de usuario completo, el autor de la llamada WlanGetProfile debe tener acceso de lectura en el perfil. De lo contrario, se producirá un error en la llamada a WlanGetProfile con un valor devuelto de ERROR_ACCESS_DENIED. Los permisos de un perfil de todo el usuario se establecen cuando se crea o guarda el perfil mediante WlanSetProfile o WlanSaveTemporaryProfile.
Windows 7:
El elemento keyMaterial devuelto en el esquema de perfil al que apunta pstrProfileXml se puede solicitar como texto no cifrado si se llama a la función WlanGetProfile con la marca WLAN_PROFILE_GET_PLAINTEXT_KEY establecida en el valor al que apunta el parámetro pdwFlags en la entrada.
Para una clave WEP, se pueden usar 5 caracteres ASCII o 10 caracteres hexadecimales para establecer la clave de texto no cifrado cuando se crea o actualiza el perfil. Sin embargo, un perfil WEP se guardará con 10 caracteres hexadecimales en la clave, independientemente de cuál se haya usado la entrada original para crear el perfil. Por lo tanto, en el perfil devuelto por la función WlanGetProfile , la clave WEP de texto no cifrado siempre se devuelve como 10 caracteres hexadecimales.
Para que la llamada a WlanGetProfile devuelva la clave de texto sin formato, los permisos wlan_secure_get_plaintext_key del tipo enumerado WLAN_SECURABLE_OBJECT deben establecerse en el subproceso que llama. La DACL también debe contener una ACE que conceda permiso WLAN_READ_ACCESS al token de acceso del subproceso que realiza la llamada. De forma predeterminada, los permisos para recuperar la clave de texto sin formato solo se permiten a los miembros del grupo Administradores en un equipo local.
Si el subproceso de llamada carece de los permisos necesarios, la función WlanGetProfile devuelve la clave cifrada en el elemento keyMaterial del perfil devuelto en el búfer al que apunta el parámetro pstrProfileXml . No se devuelve ningún error si el subproceso que realiza la llamada carece de los permisos necesarios.
De forma predeterminada, el elemento keyMaterial devuelto en el perfil al que apunta pstrProfileXml está cifrado. Si el proceso se ejecuta en el contexto de la cuenta LocalSystem en el mismo equipo, puede descifrar el material de clave llamando a la función CryptUnprotectData .
Windows Server 2008 y Windows Vista: El elemento keyMaterial devuelto en el esquema de perfil al que apunta el pstrProfileXml siempre está cifrado. Si el proceso se ejecuta en el contexto de la cuenta localSystem, puede descifrar el material de clave llamando a la función CryptUnprotectData .
Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: El material clave nunca se cifra.
Ejemplos
En el ejemplo siguiente se enumeran las interfaces LAN inalámbricas en el equipo local, se recupera información de un perfil inalámbrico específico en cada interfaz LAN inalámbrica e imprime los valores recuperados. La cadena que es la representación XML del perfil consultado también se imprime.
#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 compatible | Windows Vista, Windows XP con SP3 [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2008 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | wlanapi.h (incluya Wlanapi.h) |
| Library | Wlanapi.lib |
| Archivo DLL | Wlanapi.dll |
| Redistribuible | API LAN inalámbrica para Windows XP con SP2 |