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

Статья
11/20/2024

Функция RasSetEntryProperties изменяет сведения о подключении для записи в телефонной книге или создает новую запись телефонной книги.

Синтаксис

DWORD RasSetEntryPropertiesA(
  [in] LPCSTR      unnamedParam1,
  [in] LPCSTR      unnamedParam2,
  [in] LPRASENTRYA unnamedParam3,
  [in] DWORD       unnamedParam4,
  [in] LPBYTE      unnamedParam5,
  [in] DWORD       unnamedParam6
);

Параметры

[in] unnamedParam1

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

[in] unnamedParam2

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

Если имя записи соответствует существующей записи, RasSetEntryProperties изменяет свойства этой записи.

Если имя записи не соответствует существующей записи, RasSetEntryProperties создает новую запись телефонной книги. Для новых записей вызовите функцию RasValidateEntryName, чтобы проверить имя записи перед вызовом RasSetEntryProperties.

[in] unnamedParam3

Указатель на структуру RASENTRY, указывающую новые данные подключения, связанные с записью телефонной книги, указанной параметром lpszEntry.

Вызывающий объект должен предоставить значения для следующих элементов в структуре RASENTRY.

dwSize
szLocalPhoneNumber
szDeviceName
szDeviceType
dwFramingProtocol
dwfOptions
dwType

Windows XP или более поздней версии: поддерживается dwType.

Если значения не указаны для этих элементов, RasSetEntryProperties завершается ошибкой с ERROR_INVALID_PARAMETER.

За структурой может следовать массив строк альтернативного номера телефона, завершающего значение NULL. Последняя строка завершается двумя последовательными пустыми символами. Элемент dwAlternateOffset структуры RASENTRY содержит смещение к первой строке.

[in] unnamedParam4

Указывает размер буфера, определяемого параметром lpRasEntry.

[in] unnamedParam5

Указатель на буфер, указывающий сведения о конфигурации для конкретного устройства. Это непрозрачные сведения о конфигурации устройства TAPI. Дополнительные сведения о конфигурации устройства TAPI см. в функции lineGetDevConfig в интерфейсов программирования приложений телефонии (TAPI) в пакете SDK для платформы.

Windows XP: Этот параметр не используется. Вызывающая функция должна задать для этого параметра значение NULL.

[in] unnamedParam6

Задает размер в байтах буфера lpbDeviceInfo.

Windows XP: Этот параметр не используется. Вызывающая функция должна задать для этого параметра нулевое значение.

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

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

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

Ценность	Значение
ERROR_ACCESS_DENIED	У пользователя нет правильных привилегий. Только администратор может выполнить эту задачу.
ERROR_BUFFER_INVALID	Недопустимый адрес или буфер, указанный lpRasEntry.
ERROR_CANNOT_OPEN_PHONEBOOK	Телефонная книга повреждена или отсутствует компоненты.
ERROR_INVALID_PARAMETER	Структура RASENTRY, на которую указывает параметр lpRasEntry, не содержит достаточной информации, или указанная запись не существует в телефонной книге. Сведения о необходимых сведениях см. в описании lpRasEntry.

Замечания

При настройке свойств для подключения для всех пользователей, если вызывающее приложение указывает значение, отличное отNULL для параметра телефонной книги, lpszPhonebook, файл телефонной книги должен находиться в каталоге телефонной книги под путем данных приложения всех пользователей. Чтобы получить правильное расположение файла телефонной книги, сначала вызовите SHGetFolderPath со значением CSIDL CSIDL_COMMON_APPDATA. SHGetFolderPath возвращает путь к данным приложения для всех пользователей. Добавьте следующую строку к этому пути:

Microsoft\Network\Connections\Pbk

Объединенный путь является правильным расположением для файла телефонной книги.

Примечание Указание значения, отличного отNULL, для параметра lpszPhonebook может не поддерживаться в версиях Windows позже, чем Windows XP.

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	ras.h
библиотеки	Rasapi32.lib
DLL	Rasapi32.dll