Функция RasRenameEntryA (ras.h)

  • Статья

Функция RasRenameEntry изменяет имя записи в телефонной книге.

Синтаксис

DWORD RasRenameEntryA(
  [in] LPCSTR unnamedParam1,
  [in] LPCSTR unnamedParam2,
  [in] LPCSTR unnamedParam3
);

Параметры

[in] unnamedParam1

Указатель на строку, завершающуюся значением NULL, которая указывает полный путь и имя файла телефонной книги (PBK). Если этот параметр имеет значение NULL, функция использует текущий файл телефонной книги по умолчанию. Файл телефонной книги по умолчанию — это файл, выбранный пользователем на странице свойств Пользовательские настройки диалогового окна Сеть удаленного доступа.

Windows Me/98/95: Этот параметр всегда должен иметь значение NULL. Коммутируемая сеть сохраняет записи телефонной книги в реестре, а не в файле телефонной книги.

[in] unnamedParam2

Указатель на строку, завершающуюся значением NULL, которая указывает существующее имя записи.

[in] unnamedParam3

Указатель на строку, завершающуюся нулевым значением, которая указывает новое имя записи. Перед вызовом RasRenameEntry вызовите функцию RasValidateEntryName , чтобы проверить новое имя записи.

Возвращаемое значение

Если функция завершается успешно, возвращаемое значение будет ERROR_SUCCESS.

Если функция завершается ошибкой, возвращается один из следующих кодов ошибок или значение из кода ошибок маршрутизации и удаленного доступа или Winerror.h.

Значение Значение
ERROR_NOT_ENOUGH_MEMORY
 Функции не удалось выделить достаточно памяти для завершения операции.
ERROR_INVALID_NAME
 Недопустимое имя lpszNewEntry .
ERROR_ALREADY_EXISTS
 Запись с именем lpszNewEntry уже существует.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY
 Запись телефонной книги не существует.

Комментарии

Функция RasRenameEntry разрешает имена записей, которые не будут приняты пользовательским интерфейсом сети удаленного доступа. Имена записей, указанные в RasRenameEntry, могут состоять из любой строки, которая соответствует следующим условиям:

  1. Длина строки не может превышать RAS_MaxEntryName (как определено в Ras.h).
  2. Строка не может состоять полностью из пробелов или символов табуляции.
  3. Первый символ в строке не может быть символом точки (".").
В следующем примере кода запись телефонной книги с именем, указанным в pszOldName , переименовывается в новое имя, указанное в параметре 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;
}

Примечание

Заголовок ras.h определяет RasRenameEntry как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header ras.h
Библиотека Rasapi32.lib
DLL Rasapi32.dll

См. также раздел

RasValidateEntryName

Общие сведения о службе удаленного доступа (RAS)

Функции службы удаленного доступа