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

Статья
08/25/2023

Функция 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

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

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

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

[in] unnamedParam3

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

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

dwSize
szLocalPhoneNumber
szDeviceName
szDeviceType
dwFramingProtocol
dwfOptions
dwType

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

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

За структурой может следовать массив строк альтернативных телефонных номеров, заканчивающихся null. Последняя строка завершается двумя последовательными символами 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 со значением CSIDLCSIDL_COMMON_APPDATA. SHGetFolderPath возвращает путь к данным приложения для всех пользователей. Добавьте следующую строку в этот путь:

Microsoft\Network\Connections\Pbk

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

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

Примечание

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

Требования

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