Função RasSetCredentialsA (ras.h)

Artigo
08/25/2023

A função RasSetCredentials define as credenciais do usuário associadas a uma entrada de catálogo telefônico RAS especificada.

Sintaxe

DWORD RasSetCredentialsA(
  [in] LPCSTR            unnamedParam1,
  [in] LPCSTR            unnamedParam2,
  [in] LPRASCREDENTIALSA unnamedParam3,
  [in] BOOL              unnamedParam4
);

Parâmetros

[in] unnamedParam1

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o caminho completo e o nome de arquivo de um arquivo de catálogo telefônico (PBK). Se esse parâmetro for NULL, a função usará o arquivo de catálogo telefônico padrão atual. O arquivo de catálogo telefônico padrão é aquele selecionado pelo usuário na folha de propriedades Preferências do Usuário da caixa de diálogo Rede Discada .

[in] unnamedParam2

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome de uma entrada de catálogo telefônico.

[in] unnamedParam3

Um ponteiro para uma estrutura RASCREDENTIALS que especifica as credenciais do usuário a serem definidas para a entrada de catálogo telefônico especificada. Antes de chamar RasSetCredentials, defina o membro dwSize da estrutura sizeof(RASCREDENTIALS) como e defina o membro dwMask para indicar as informações de credencial a serem definidas.

[in] unnamedParam4

Um valor que especifica se RasSetCredentials limpa as credenciais existentes definindo-as como a cadeia de caracteres vazia, "". Se esse sinalizador for TRUE, o membro dwMask da estrutura RASCREDENTIALS indicará quais credenciais a função define para a cadeia de caracteres vazia. Se esse sinalizador for FALSE, a função definirá as credenciais indicadas de acordo com o conteúdo de seus membros RASCREDENTIALS correspondentes .

Valor retornado

Se a função for bem-sucedida, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado será um dos seguintes códigos de erro ou um valor de Códigos de Erro de Roteamento e Acesso Remoto ou WinError.h.

Valor	Significado
ERROR_CANNOT_OPEN_PHONEBOOK	A lista telefônica especificada não pode ser encontrada.
ERROR_INVALID_PARAMETER	O parâmetro lpCredentials era NULL ou a entrada especificada não existe na lista telefônica.
ERROR_ACCESS_DENIED	Uma das seguintes condições ocorreu: O aplicativo de chamada tentou definir credenciais padrão para uma conexão por usuário. As credenciais padrão só podem ser definidas para uma conexão de todos os usuários. O usuário não tem os privilégios corretos para definir chaves ou credenciais pré-compartilhadas para todos os usuários no caso de conectores de todos os usuários. Somente os administradores podem concluir essas tarefas.

Comentários

A função RasSetCredentials define as credenciais do usuário associadas a uma entrada de catálogo telefônico RAS especificada. As credenciais armazenadas com uma entrada de catálogo telefônico são as credenciais do último usuário para se conectar com êxito usando a entrada de catálogo telefônico especificada ou as credenciais especificadas posteriormente em uma chamada para a função RasSetCredentials ou RasSetEntryDialParams para a entrada do catálogo telefônico.

A função RasSetCredentials é a maneira preferencial de armazenar credenciais com segurança com uma entrada de catálogo telefônico. RasSetCredentials substitui a função RasSetEntryDialParams , que pode não ter suporte em versões futuras do sistema operacional Windows.

Um identificador de senha é "*********** (16 asteriscos). Se você chamar RasGetCredentials e receber 16 *s de volta no campo de senha, você terá uma senha armazenada e, por motivos de segurança, ela não será entregue a você em texto sem formatação. Se o membro szPassword da estrutura RASCREDENTIALS contiver o identificador de senha (16 *s) retornado por RasGetCredentials ou RasGetEntryDialParams, a próxima chamada para RasSetCredentials não alterará a senha salva.

Para definir as credenciais padrão para uma conexão de todos os usuários, defina o sinalizador RASCM_DefaultCreds no membro dwMask da estrutura RASCREDENTIALS apontada pelo parâmetro lpCredentials . Se você tentar definir credenciais padrão para uma conexão por usuário, RasSetCredentials retornará ERROR_ACCESS_DENIED.

Ao definir credenciais para uma conexão de todos os usuários, se o aplicativo de chamada especificar um valor não NULL para o parâmetro phone-book, lpszPhonebook, o arquivo de catálogo telefônico deverá estar localizado no diretório do catálogo telefônico abaixo do caminho de dados do aplicativo de todos os usuários. Para obter o local correto para o arquivo de catálogo telefônico, primeiro chame SHGetFolderPath com um valor CSIDL de CSIDL_COMMON_APPDATA. SHGetFolderPath retorna o caminho de dados do aplicativo de todos os usuários. Acrescente a seguinte cadeia de caracteres a este caminho:

Microsoft\Network\Connections\Pbk

O caminho combinado é o local correto para o arquivo de catálogo telefônico.

Nota A especificação de um valor não NULL para o parâmetro lpszPhonebook pode não ter suporte em versões posteriores do sistema operacional Windows.

Para definir uma chave pré-compartilhada, use o sinalizador RASCM_PreSharedKey no RASCREDENTIALS. campo dwMask .

Observação

O cabeçalho ras.h define RasSetCredentials como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ras.h
Biblioteca	Rasapi32.lib
DLL	Rasapi32.dll