Função RasRenameEntryA (ras.h)

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

Windows Me/98/95: Esse parâmetro sempre deve ser NULL. A rede discada armazena entradas de catálogo telefônico no registro em vez de em um arquivo de catálogo 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.

Retornar valor

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 nome lpszNewEntry é inválido.
ERROR_ALREADY_EXISTS	Já existe uma entrada com o nome lpszNewEntry .
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	A entrada da lista telefônica não existe.

Comentários

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 em RasRenameEntry podem consistir em qualquer cadeia de caracteres que adere às seguintes condições:

1. A cadeia de caracteres não pode ter um comprimento maior que RAS_MaxEntryName (conforme definido em Ras.h).
2. A cadeia de caracteres não pode consistir inteiramente em caracteres de espaço ou tabulação.
3. 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;
}

Observação

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

Requisito	Valor
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

Confira também

RasValidateEntryName

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

Funções do serviço de acesso remoto