Função RasSetCredentialsA (ras.h)

A função RasSetCredentials define as credenciais do usuário associadas a uma entrada de lista telefônica 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 do arquivo de um PBK (lista telefônica). Se esse parâmetro for NULL, a função usará o arquivo de agendamento telefônico padrão atual. O arquivo de lista telefônica padrão é o 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 lista telefônica.

[in] unnamedParam3

Um ponteiro para uma estrutura RASCREDENTIALS que especifica as credenciais do usuário a serem definidas para a entrada de lista telefônica especificada. Antes de chamar RasSetCredentials, defina o dwSize membro da estrutura para sizeof(RASCREDENTIALS) 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 para a cadeia de caracteres vazia, "". Se esse sinalizador for TRUE, o dwMask membro 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 de retorno

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 foi 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.

Observações

A função RasSetCredentials define as credenciais do usuário associadas a uma entrada de lista telefônica RAS especificada. As credenciais armazenadas com uma entrada de lista telefônica são as credenciais do último usuário a se conectar com êxito usando a entrada de catálogo telefônico especificada ou as credenciais especificadas posteriormente em uma chamada para o RasSetCredentials ou rasSetEntryDialParams função 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 lista telefônica. 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á retornada a você em texto sem formatação. Se o szPassword membro da estrutura RASCREDENTIALS contém 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 dwMask membro da estrutura de RASCREDENTIALS apontado 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 de lista telefônica, lpszPhonebook, o arquivo de lista telefônica deverá estar localizado no diretório do catálogo telefônico abaixo do caminho de dados do aplicativo para todos os usuários. Para obter o local correto para o arquivo de lista telefônica, primeira chamada SHGetFolderPath com um valor CSIDL de CSIDL_COMMON_APPDATA. SHGetFolderPath retorna o caminho de dados do aplicativo para 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 lista telefônica.

Observação Especificar 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 noRASCREDENTIALS .campo dwMask.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	ras.h
biblioteca	Rasapi32.lib
de DLL	Rasapi32.dll

Consulte também

RASCREDENTIALS

RasDial

RasGetCredentials

RasSetEntryDialParams

Visão geral do RAS (Serviço de Acesso Remoto)

Funções do Serviço de Acesso Remoto