Función WlanSetProfile (wlanapi.h)
La función WlanSetProfile establece el contenido de un perfil específico.
Sintaxis
DWORD WlanSetProfile(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[in] DWORD dwFlags,
[in] LPCWSTR strProfileXml,
[in, optional] LPCWSTR strAllUserProfileSecurity,
[in] BOOL bOverwrite,
[in] PVOID pReserved,
[out] DWORD *pdwReasonCode
);
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.
[in] dwFlags
Marcas que se van a establecer en el perfil.
Windows XP con SP3 y la API de LAN inalámbrica para Windows XP con SP2: dwFlags debe ser 0. No se admiten perfiles por usuario.
[in] strProfileXml
Contiene la representación XML del perfil. El elemento WLANProfile es el elemento de perfil raíz. Para ver perfiles de ejemplo, consulta Wireless Profile Samples. No hay ninguna longitud de cadena máxima predefinida.
Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: El perfil proporcionado debe cumplir los criterios de compatibilidad descritos en Compatibilidad de perfiles inalámbricos.
[in, optional] strAllUserProfileSecurity
Establece la cadena del descriptor de seguridad en el perfil de todo el usuario. Para obtener más información sobre los permisos de perfil, vea la sección Comentarios.
Si dwFlags se establece en WLAN_PROFILE_USER, este parámetro se omite.
Si este parámetro se establece en NULL para un nuevo perfil de usuario completo, se usa el descriptor de seguridad asociado al objeto wlan_secure_add_new_all_user_profiles. Si una llamada a WlanSetSecuritySettings no ha modificado el descriptor de seguridad, todos los usuarios tienen permisos predeterminados en un nuevo perfil de usuario completo. Llame a WlanGetSecuritySettings para obtener los permisos predeterminados asociados al objeto wlan_secure_add_new_all_user_profiles.
Si este parámetro se establece en NULL para un perfil de usuario completo existente, no se cambian los permisos del perfil.
Si este parámetro no es NULL para un perfil de usuario completo, la cadena de descriptor de seguridad asociada al perfil se crea o modifica después de crear y analizar el objeto descriptor de seguridad como una cadena.
Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: Este parámetro debe ser NULL.
[in] bOverwrite
Especifica si este perfil está sobrescribir un perfil existente. Si este parámetro es FALSE y el perfil ya existe, no se sobrescribirá el perfil existente y se devolverá un error.
[in] pReserved
Reservado para uso futuro. Debe establecerse en NULL.
[out] pdwReasonCode
Valor WLAN_REASON_CODE que indica por qué el perfil no es válido.
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 para establecer el perfil.
Cuando se llama con dwFlags establecido en 0, es decir, al establecer un perfil de usuario completo - WlanSetProfile recupera la lista de control de acceso discrecional (DACL) almacenada con el objeto wlan_secure_add_new_all_user_profiles . Cuando se llama con dwFlags establecido en WLAN_PROFILE_USER , es decir, al establecer un perfil por usuario, WlanSetProfile recupera la lista de control de acceso discrecional (DACL) almacenada con el objeto wlan_secure_add_new_per_user_profiles . En cualquier caso, si la DACL no contiene una entrada de control de acceso (ACE) que concede WLAN_WRITE_ACCESS permiso al token de acceso del subproceso que realiza la llamada, WlanSetProfile devuelve ERROR_ACCESS_DENIED. |
|
strProfileXml especifica una red que ya existe. Normalmente, este valor devuelto se usa cuando bOverwrite es FALSE; Sin embargo, si bOverwrite es TRUE y dwFlags especifica un tipo de perfil diferente al usado por el perfil existente, no se sobrescribirá el perfil existente y se devolverá ERROR_ALREADY_EXISTS . |
|
El perfil especificado por strProfileXml no es válido. Si se devuelve este valor, pdwReasonCode especifica el motivo por el que el perfil no es válido. |
|
Se produjo una de las condiciones siguientes:
<ConfigBlob>00</ConfigBlob> en el perfil.
|
|
La interfaz no admite una o varias de las funcionalidades especificadas en el perfil. Por ejemplo, si un perfil especifica el uso de WPA2 cuando la NIC solo admite WPA, se devuelve este código de error. Además, si un perfil especifica el uso del modo FIPS cuando la NIC no admite el modo FIPS, se devuelve este código de error. |
|
Varios códigos de error. |
Comentarios
La función WlanSetProfile se puede usar para agregar un nuevo perfil LAN inalámbrico o reemplazar un perfil LAN inalámbrico existente.
Se agrega un nuevo perfil en la parte superior de la lista después de los perfiles de directiva de grupo. La posición de un perfil en la lista no cambia si se sobrescribe un perfil existente. Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2:
Los perfiles ad hoc aparecen después de los perfiles de infraestructura de la lista de perfiles. Si crea un nuevo perfil ad hoc, se coloca en la parte superior de la lista ad hoc, después de la directiva de grupo y los perfiles de infraestructura.
No se admiten los perfiles de invitado 802.1X, los perfiles del Servicio de aprovisionamiento inalámbrico (WPS) y los perfiles con Wi-Fi autenticación de Access-None protegida (WPA-None). Esto significa que este perfil no se puede crear, eliminar, enumerar ni tener acceso a él mediante funciones wifi nativas. Cualquier perfil que ya esté en la lista de perfiles preferidos permanecerá en la lista y su posición en la lista con respecto a otros perfiles se fija a menos que cambie la posición de los otros perfiles.
Puede llamar a WlanSetProfile en un perfil que contenga una clave de texto no cifrado (es decir, un perfil con el elemento protegido presente y establecido en FALSE). Antes de guardar el perfil en el almacén de perfiles, el material de clave se cifra automáticamente. Cuando el perfil se recupera posteriormente del almacén de perfiles mediante una llamada a WlanGetProfile, se devuelve el material de clave cifrada. Windows XP con SP3 y LAN inalámbrica API para Windows XP con SP2: El material de clave nunca se cifra.
Los perfiles de todos los usuarios tienen tres permisos asociados: lectura, escritura y ejecución. Si un usuario tiene acceso de lectura, el usuario puede ver los permisos de perfil. Si un usuario tiene acceso de ejecución, 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 acceso de escritura, el usuario tiene acceso de ejecución y el usuario también puede modificar y eliminar permisos asociados a un perfil.
A continuación se describe el procedimiento para crear un objeto descriptor de seguridad y analizarlo como una cadena.
- Llame a InitializeSecurityDescriptor para crear un descriptor de seguridad en la memoria.
- Llame a SetSecurityDescriptorOwner.
- Llame a InitializeAcl para crear una lista de control de acceso discrecional (DACL) en memoria.
- Llame a AddAccessAllowedAce o AddAccessDeniedAce para agregar entradas de control de acceso (ACE) a la DACL. Establezca el parámetro AccessMask en uno de los siguientes según corresponda:
- WLAN_READ_ACCESS
- WLAN_EXECUTE_ACCESS
- WLAN_WRITE_ACCESS
- Llame a SetSecurityDescriptorDacl para agregar la DACL al descriptor de seguridad.
- Llame a ConvertSecurityDescriptorToStringSecurityDescriptor para convertir el descriptor en cadena.
Para cada perfil de LAN inalámbrico usado por el servicio Native Wifi AutoConfig, Windows mantiene el concepto de datos de usuario personalizados. Estos datos de usuario personalizados no existen inicialmente, pero se pueden establecer llamando a la función WlanSetProfileCustomUserData . Los datos de usuario personalizados se restablecen a vacíos cada vez que se modifica el perfil mediante una llamada a la función WlanSetProfile . Una vez establecidos los datos de usuario personalizados, se puede acceder a estos datos mediante la función WlanGetProfileCustomUserData .
Todas las funciones LAN inalámbricas requieren un GUID de interfaz para la interfaz inalámbrica al realizar operaciones de perfil. Cuando se quita una interfaz inalámbrica, su estado se borra del servicio LAN inalámbrico (WLANSVC) y no se pueden realizar operaciones de perfil.
La función WlanSetProfile puede producir un error con ERROR_INVALID_PARAMETER si la interfaz inalámbrica especificada en el parámetro pInterfaceGuid se ha quitado del sistema (un adaptador inalámbrico USB que se ha quitado, por ejemplo).
El comando netsh wlan add profile proporciona una funcionalidad similar en la línea de comandos. Para obtener más información, consulta Netsh Commands for Wireless Local Area Network (wlan).
Requisitos
| Requisito | Value |
|---|---|
| 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 |
Consulte también
ConvertSecurityDescriptorToStringSecurityDescriptor