Função RasSetEntryDialParamsA (ras.h)

Artigo
11/20/2024

A função RasSetEntryDialParams altera as informações de conexão salvas pela última chamada bem-sucedida para a função RasDial ou RasSetEntryDialParams para uma entrada de catálogo telefônico especificada.

Sintaxe

DWORD RasSetEntryDialParamsA(
  [in] LPCSTR           unnamedParam1,
  [in] LPRASDIALPARAMSA unnamedParam2,
  [in] BOOL             unnamedParam3
);

Parâmetros

[in] unnamedParam1

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 .

Windows Me/98/95: Esse parâmetro sempre deve ser NULL. A rede discada armazena entradas de agendamento telefônico no registro, em vez de em um arquivo de agendamento telefônico.

[in] unnamedParam2

Ponteiro para a estrutura RASDIALPARAMS que especifica os parâmetros de conexão a serem associados à entrada do catálogo telefônico. RasSetEntryDialParams usa os membros da estrutura da seguinte maneira.

Membro	Significado
dwSize	Deve especificar o tamanho de (RASDIALPARAMS) para identificar a versão da estrutura.
szEntryName	Uma cadeia de caracteres terminada em nulo que identifica a entrada da lista telefônica para a qual definir parâmetros.
szPhoneNumber	Não usado. Definir como NULL.
szCallbackNumber	Uma cadeia de caracteres terminada em nulo que contém o número de telefone de retorno de chamada. Se szCallbackNumber for uma cadeia de caracteres vazia ( "" ), o número de retorno de chamada não será alterado.
szUserName	Uma cadeia de caracteres terminada em nulo que contém o nome de logon do usuário associado a essa entrada. Se szUserName for uma cadeia de caracteres vazia, o nome de usuário não será alterado.
szPassword	Uma cadeia de caracteres terminada em nulo que contém a senha do usuário especificada por szUserName. Se szUserName for uma cadeia de caracteres vazia, a senha não será alterada. Se szPassword for uma cadeia de caracteres vazia e fRemovePassword for FALSE, a senha será definida como a cadeia de caracteres vazia. Se fRemovePassword for VERDADEIRO, a senha armazenada nesta entrada de lista telefônica para o usuário especificado pelo szUserName do será removida independentemente do conteúdo da cadeia de caracteres szPassword . Windows NT 4.0: A senha é alterada para a cadeia de caracteres especificada por szPassword independentemente de szUserName for uma cadeia de caracteres vazia. Windows XP/2000: Se szPassword contiver o identificador de senha retornado por RasGetCredentials ou RasGetEntryDialParams, RasSetEntryDialParams retorna com êxito sem alterar nenhuma senha salva no momento.
szDomain	Uma cadeia de caracteres terminada em nulo que contém o nome do domínio no qual fazer logon. Se szDomain for uma cadeia de caracteres vazia, o nome de domínio não será alterado.
dwSubEntry	Especifica o índice (baseado em um) da subentrada inicial a ser discada ao estabelecer a conexão.
dwCallbackId	Especifica um valor definido pelo aplicativo que o RAS passa para a função de retorno de chamada rasDialFunc2 .

[in] unnamedParam3

Especifica se é necessário remover a senha armazenada da entrada da lista telefônica para o usuário indicado por lprasdialparams–>szUserName. Se fRemovePassword for verdadeiro, a senha será removida. Definir fRemovePassword como VERDADEIRO é equivalente a marcar a caixa de seleção "Cancelar Senha" na Rede Discada. Ao definir a senha ou outras propriedades de uma entrada de lista telefônica, defina fRemovePassword como false.

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	Descrição
ERROR_BUFFER_INVALID	O endereço ou buffer especificado por lprasdialparams é inválido.
ERROR_CANNOT_OPEN_PHONEBOOK	A lista telefônica está corrompida ou está faltando componentes.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	A entrada da lista telefônica não existe.

Observações

Para criar uma nova entrada de lista telefônica, use a função RasSetEntryProperties.

Windows XP ou posterior: Não use a função RasSetEntryDialParams . Para definir as credenciais de uma entrada de lista telefônica, use a função RasSetCredentials. Defina os membros não credenciais de RASDIALPARAMS (por exemplo, szCallbackNumber, dwSubEntryou dwCallbackId) diretamente na estrutura RASDIALPARAMS passada como um parâmetro para a função RasDial.

Nota

O cabeçalho ras.h define RasSetEntryDialParams 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