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

Статья
11/20/2024

Функция RasSetEntryDialParams изменяет сведения о подключении, сохраненные последним успешным вызовом RasDial или RasSetEntryDialParams для указанной записи телефонной книги.

Синтаксис

DWORD RasSetEntryDialParamsA(
  [in] LPCSTR           unnamedParam1,
  [in] LPRASDIALPARAMSA unnamedParam2,
  [in] BOOL             unnamedParam3
);

Параметры

[in] unnamedParam1

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

Windows Me/98/95: этот параметр всегда должен быть NULL. Подключение к сети хранит записи телефонной книги в реестре, а не в файле телефонной книги.

[in] unnamedParam2

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

Член	Значение
dwSize	Необходимо указать размер (RASDIALPARAMS), чтобы определить версию структуры.
szEntryName	Строка, завершающая значение NULL, идентифицирующая запись телефонной книги для задания параметров.
szPhoneNumber	Не используется. Установите значение NULL.
szCallbackNumber	Строка, завершающаяся значением NULL, содержащая номер телефона обратного вызова. Если szCallbackNumber является пустой строкой ("), номер обратного вызова не изменяется.
szUserName	Строка, завершающаяся значением NULL, содержащая имя входа пользователя, связанного с этой записью. Если szUserName является пустой строкой, имя пользователя не изменяется.
szPassword	Строка, завершающая значение NULL, содержащая пароль для пользователя, указанного szUserName. Если szUserName является пустой строкой, пароль не изменяется. Если szPassword является пустой строкой и fRemovePassword false, пароль имеет пустую строку. Если fRemovePasswordTRUE, пароль, хранящийся в этой записи телефонной книги для пользователя, указанного szUserName, удаляется независимо от содержимого строки szPassword. Windows NT 4.0: Пароль изменяется на строку, указанную szPassword независимо от того, является ли szUserName пустой строкой. Windows XP/2000: Если szPassword содержит дескриптор пароля, возвращенный RasGetCredentials или RasGetEntryDialParams, RasSetEntryDialParams успешно возвращается без изменения пароля.
szDomain	Строка, завершающаяся значением NULL, содержащая имя домена, в котором требуется войти. Если szDomain является пустой строкой, доменное имя не изменяется.
dwSubEntry	Задает (одноуровневый) индекс начального подзадачи для набора при установке подключения.
dwCallbackId	Указывает определяемое приложением значение, которое RAS передает функции обратного вызова RasDialFunc 2.

[in] unnamedParam3

Указывает, следует ли удалять сохраненный пароль записи телефонной книги для пользователя, указанного lprasdialparams->szUserName. Если fRemovePassword TRUE, пароль удаляется. Для параметра fRemovePassword значение TRUE эквивалентно проверке флажка "Unsave Password" (Отмена пароля) в сети с телефонным подключением. При настройке пароля или других свойств записи телефонной книги задайте fRemovePassword значение FALSE.

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

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

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

Ценность	Описание
ERROR_BUFFER_INVALID	Адрес или буфер, указанный lprasdialparams, является недопустимым.
ERROR_CANNOT_OPEN_PHONEBOOK	Телефонная книга повреждена или отсутствует компоненты.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	Запись телефонной книги не существует.

Замечания

Чтобы создать новую запись телефонной книги, используйте функцию RasSetEntryProperties.

Windows XP или более поздней версии: не используйте функцию RasSetEntryDialParams. Чтобы задать учетные данные для записи телефонной книги, используйте функцию RasSetCredentials. Задайте члены RASDIALPARAMS (например, szCallbackNumber, dwSubEntryили dwCallbackId) непосредственно в структуре RASDIALPARAMS, переданной в функцию RasDial.

Заметка

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

Требования

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