Função WlanSetProfile (wlanapi.h)
A função WlanSetProfile define o conteúdo de um perfil específico.
Sintaxe
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
O identificador de sessão do cliente, obtido por uma chamada anterior para a função WlanOpenHandle .
[in] pInterfaceGuid
O GUID da interface.
[in] dwFlags
Os sinalizadores a serem definidos no perfil.
Windows XP com SP3 e API lan sem fio para Windows XP com SP2: dwFlags deve ser 0. Não há suporte para perfis por usuário.
[in] strProfileXml
Contém a representação XML do perfil. O elemento WLANProfile é o elemento de perfil raiz. Para exibir perfis de exemplo, consulte Exemplos de perfil sem fio. Não há nenhum comprimento máximo de cadeia de caracteres predefinido.
Windows XP com SP3 e API lan sem fio para Windows XP com SP2: O perfil fornecido deve atender aos critérios de compatibilidade descritos em Compatibilidade de Perfil Sem Fio.
[in, optional] strAllUserProfileSecurity
Define a cadeia de caracteres do descritor de segurança no perfil de todos os usuários. Para obter mais informações sobre permissões de perfil, consulte a seção Comentários.
Se dwFlags estiver definido como WLAN_PROFILE_USER, esse parâmetro será ignorado.
Se esse parâmetro for definido como NULL para um novo perfil de todos os usuários, o descritor de segurança associado ao objeto wlan_secure_add_new_all_user_profiles será usado. Se o descritor de segurança não tiver sido modificado por uma chamada WlanSetSecuritySettings , todos os usuários terão permissões padrão em um novo perfil de todos os usuários. Chame WlanGetSecuritySettings para obter as permissões padrão associadas ao objeto wlan_secure_add_new_all_user_profiles.
Se esse parâmetro for definido como NULL para um perfil de todos os usuários existente, as permissões do perfil não serão alteradas.
Se esse parâmetro não for NULL para um perfil de todos os usuários, a cadeia de caracteres do descritor de segurança associada ao perfil será criada ou modificada depois que o objeto descritor de segurança for criado e analisado como uma cadeia de caracteres.
Windows XP com SP3 e API lan sem fio para Windows XP com SP2: Esse parâmetro deve ser NULL.
[in] bOverwrite
Especifica se esse perfil está substituindo um perfil existente. Se esse parâmetro for FALSE e o perfil já existir, o perfil existente não será substituído e um erro será retornado.
[in] pReserved
Reservado para uso futuro. Deve ser definido como NULL.
[out] pdwReasonCode
Um valor WLAN_REASON_CODE que indica por que o perfil não é válido.
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 para definir o perfil.
Quando chamado com dwFlags definido como 0 - ou seja, ao definir um perfil de todos os usuários - WlanSetProfile recupera a DACL (lista de controle de acesso discricionário) armazenada com o objeto wlan_secure_add_new_all_user_profiles . Quando chamado com dwFlags definido como WLAN_PROFILE_USER - ou seja, ao definir um perfil por usuário - WlanSetProfile recupera a DACL (lista de controle de acesso discricionário) armazenada com o objeto wlan_secure_add_new_per_user_profiles . Em ambos os casos, se a DACL não contiver uma ACE (entrada de controle de acesso) que conceda permissão WLAN_WRITE_ACCESS ao token de acesso do thread de chamada, wlanSetProfile retornará ERROR_ACCESS_DENIED. |
|
strProfileXml especifica uma rede que já existe. Normalmente, esse valor retornado é usado quando bOverwrite é FALSE; no entanto, se bOverwrite for TRUE e dwFlags especificar um tipo de perfil diferente do usado pelo perfil existente, o perfil existente não será substituído e ERROR_ALREADY_EXISTS será retornado. |
|
O perfil especificado por strProfileXml não é válido. Se esse valor for retornado, pdwReasonCode especificará o motivo pelo qual o perfil é inválido. |
|
Uma das seguintes condições ocorreu:
<ConfigBlob>00</ConfigBlob> no perfil.
|
|
A interface não dá suporte a um ou mais dos recursos especificados no perfil. Por exemplo, se um perfil especificar o uso do WPA2 quando a NIC oferecer suporte apenas ao WPA, esse código de erro será retornado. Além disso, se um perfil especificar o uso do modo FIPS quando a NIC não oferecer suporte ao modo FIPS, esse código de erro será retornado. |
|
Vários códigos de erro. |
Comentários
A função WlanSetProfile pode ser usada para adicionar um novo perfil de LAN sem fio ou substituir um perfil de LAN sem fio existente.
Um novo perfil é adicionado na parte superior da lista após os perfis de política de grupo. A posição de um perfil na lista não será alterada se um perfil existente for substituído. Windows XP com SP3 e API lan sem fio para Windows XP com SP2:
Os perfis ad hoc aparecem após os perfis de infraestrutura na lista de perfis. Se você criar um novo perfil ad hoc, ele será colocado na parte superior da lista ad hoc, após a política de grupo e os perfis de infraestrutura.
Não há suporte para perfis de convidado 802.1X, perfis do WPS (Serviço de Provisionamento Sem Fio) e perfis com Wi-Fi autenticação WPA-None (Access-None Protegida). Isso significa que esse perfil não pode ser criado, excluído, enumerado ou acessado usando funções wi-fi nativas. Qualquer perfil desse tipo já na lista de perfis preferenciais permanecerá na lista e sua posição na lista relativa a outros perfis será corrigida, a menos que a posição dos outros perfis seja alterada.
Você pode chamar WlanSetProfile em um perfil que contém uma chave de texto sem formatação (ou seja, um perfil com o elemento protegido presente e definido como FALSE). Antes que o perfil seja salvo no repositório de perfil, o material da chave é criptografado automaticamente. Quando o perfil é recuperado posteriormente do repositório de perfil chamando WlanGetProfile, o material de chave criptografado é retornado. Windows XP com SP3 e API lan sem fio para Windows XP com SP2: O material da chave nunca é criptografado.
Os perfis de todos os usuários têm três permissões associadas: leitura, gravação e execução. Se um usuário tiver acesso de leitura, o usuário poderá exibir permissões de perfil. Se um usuário tiver acesso de execução, o usuário terá acesso de leitura e o usuário também poderá se conectar e desconectar de uma rede usando o perfil. Se um usuário tiver acesso de gravação, o usuário terá acesso de execução e o usuário também poderá modificar e excluir permissões associadas a um perfil.
A seguir, descreve o procedimento para criar um objeto descritor de segurança e analisá-lo como uma cadeia de caracteres.
- Chame InitializeSecurityDescriptor para criar um descritor de segurança na memória.
- Chame SetSecurityDescriptorOwner.
- Chame InitializeAcl para criar uma DACL (lista de controle de acesso discricionário) na memória.
- Chame AddAccessAllowedAce ou AddAccessDeniedAce para adicionar ACEs (entradas de controle de acesso) à DACL. Defina o parâmetro AccessMask como um dos seguintes, conforme apropriado:
- WLAN_READ_ACCESS
- WLAN_EXECUTE_ACCESS
- WLAN_WRITE_ACCESS
- Chame SetSecurityDescriptorDacl para adicionar a DACL ao descritor de segurança.
- Chame ConvertSecurityDescriptorToStringSecurityDescriptor para converter o descritor em cadeia de caracteres.
Para cada perfil de LAN sem fio usado pelo serviço de Configuração Automática de Wi-Fi Nativo, o Windows mantém o conceito de dados de usuário personalizados. Esses dados de usuário personalizados são inicialmente inexistentes, mas podem ser definidos chamando a função WlanSetProfileCustomUserData . Os dados personalizados do usuário são redefinidos para vazios sempre que o perfil é modificado chamando a função WlanSetProfile . Depois que os dados de usuário personalizados tiverem sido definidos, esses dados poderão ser acessados usando a função WlanGetProfileCustomUserData .
Todas as funções lan sem fio exigem um GUID de interface para a interface sem fio ao executar operações de perfil. Quando uma interface sem fio é removida, seu estado é removido do WLANSVC (Wireless LAN Service) e nenhuma operação de perfil é possível.
A função WlanSetProfile poderá falhar com ERROR_INVALID_PARAMETER se a interface sem fio especificada no parâmetro pInterfaceGuid tiver sido removida do sistema (um adaptador sem fio USB que foi removido, por exemplo).
O comando netsh wlan add profile fornece funcionalidade semelhante na linha de comando. Para obter mais informações, consulte Comandos netsh para rede local sem fio (wlan).
Requisitos
| Requisito | Valor |
|---|---|
| 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 |
Confira também
ConvertSecurityDescriptorToStringSecurityDescriptor