Função RasRenameEntryA (ras.h)

Artigo
11/20/2024

A função RasRenameEntry altera o nome de uma entrada em uma lista telefônica.

Sintaxe

DWORD RasRenameEntryA(
  [in] LPCSTR unnamedParam1,
  [in] LPCSTR unnamedParam2,
  [in] LPCSTR 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 uma cadeia de caracteres terminada em nulo que especifica um nome de entrada existente.

[in] unnamedParam3

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o novo nome de entrada. Antes de chamar RasRenameEntry, chame a função RasValidateEntryName para validar o novo nome de entrada.

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_NOT_ENOUGH_MEMORY	A função não pôde alocar memória suficiente para concluir a operação.
ERROR_INVALID_NAME	O lpszNewEntry nome é inválido.
ERROR_ALREADY_EXISTS	Já existe uma entrada com o lpszNewEntry nome.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	A entrada da lista telefônica não existe.

Observações

A função RasRenameEntry permite nomes de entrada que não seriam aceitos pela interface do usuário de rede discada. Os nomes de entrada especificados no RasRenameEntry podem consistir em qualquer cadeia de caracteres que adere às seguintes condições:

A cadeia de caracteres não pode ter um comprimento maior que RAS_MaxEntryName (conforme definido em Ras.h).
A cadeia de caracteres não pode consistir inteiramente em caracteres de espaço ou guia.
O primeiro caractere na cadeia de caracteres não pode ser um caractere de ponto (".").

O exemplo de código a seguir renomeia a entrada do catálogo telefônico com o nome especificado por pszOldName para o novo nome especificado por pszNewName.

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include <tchar.h>

DWORD main (){

    DWORD dwErr = ERROR_SUCCESS;
    LPCTSTR pszOldName = L"RAS Connection 1\0";
    LPCTSTR pszNewName = L"RAS Connection 2\0";

    dwErr = RasValidateEntryName(NULL, pszNewName);
    if (ERROR_SUCCESS != dwErr)
    {
        printf("RasValidateEntryName failed: Error = %d\n", dwErr);
        return dwErr;
    }

    dwErr = RasRenameEntry(NULL, pszOldName, pszNewName);
    if (ERROR_SUCCESS != dwErr)
    {
        printf("RasRenameEntry failed: Error = %d\n", dwErr);
        return dwErr;
    }

    printf("Successfully renamed entry '%s' to '%s'\n", pszOldName, pszNewName);

    return 0;
}

Nota

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

RasValidateEntryName

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

Funções do Serviço de Acesso Remoto

Compartilhar via