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

Статья
11/20/2024

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

Синтаксис

DWORD RasSetCredentialsA(
  [in] LPCSTR            unnamedParam1,
  [in] LPCSTR            unnamedParam2,
  [in] LPRASCREDENTIALSA unnamedParam3,
  [in] BOOL              unnamedParam4
);

Параметры

[in] unnamedParam1

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

[in] unnamedParam2

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

[in] unnamedParam3

Указатель на структуру RASCREDENTIALS, указывающую учетные данные пользователя, заданные для указанной записи телефонной книги. Перед вызовом RasSetCredentials задайте для элемента dwSize dwSizesizeof(RASCREDENTIALS) и задайте элемент dwMask, чтобы указать учетные данные, которые необходимо задать.

[in] unnamedParam4

Значение, указывающее, RasSetCredentials очищает существующие учетные данные, задав их пустой строке "". Если этот флаг TRUE, элемент dwMask RASCREDENTIALS указывает учетные данные, которые функция задает пустой строке. Если этот флаг FALSE, функция задает указанные учетные данные в соответствии с содержимым соответствующих членов RASCREDENTIALS.

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

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

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

Ценность	Значение
ERROR_CANNOT_OPEN_PHONEBOOK	Не удается найти указанную телефонную книгу.
ERROR_INVALID_PARAMETER	Параметр lpCredentials был nullили указанная запись не существует в телефонной книге.
ERROR_ACCESS_DENIED	Произошло одно из следующих условий: Вызывающее приложение попыталось задать учетные данные по умолчанию для подключения для каждого пользователя. Учетные данные по умолчанию можно задать только для подключения всех пользователей. У пользователя нет правильных привилегий, чтобы задать предварительные ключи или учетные данные для всех пользователей в случае подключения всех пользователей. Только администраторы могут выполнять эти задачи.

Замечания

Функция RasSetCredentials задает учетные данные пользователя, связанные с указанной записью телефонной книги RAS. Учетные данные, хранящиеся в записи телефонной книги, — это учетные данные последнего пользователя для успешного подключения с помощью указанной записи телефонной книги или учетные данные, которые впоследствии указаны в вызове RasSetCredentials или функции RasSetEntryDialParams для записи телефонной книги.

Функция RasSetCredentials является предпочтительным способом безопасного хранения учетных данных с записью телефонной книги. RasSetCredentials заменяет функцию RasSetEntryDialParams, которая может не поддерживаться в будущих выпусках операционной системы Windows.

Дескриптор пароля — "****************" (16 звездочек). Если вы вызываете RasGetCredentials и получаете 16 *s обратно в поле пароля, у вас есть сохраненный пароль и, по соображениям безопасности, он не будет возвращен вам в виде обычного текста. Если элемент szPassword структуры RASCREDENTIALS содержит дескриптор пароля (16 *s), возвращенный RasGetCredentials или RasGetEntryDialParams, следующий вызов RasSetCredentials не изменит сохраненный пароль.

Чтобы задать учетные данные по умолчанию для подключения всех пользователей, задайте флаг RASCM_DefaultCreds в элементе dwMask члена rasCREDENTIALS, на который указывает параметр lpCredentials. Если вы пытаетесь задать учетные данные по умолчанию для подключения для каждого пользователя, RasSetCredentials возвращает ERROR_ACCESS_DENIED.

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

Microsoft\Network\Connections\Pbk

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

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

Чтобы задать предварительный общий ключ, используйте флаг RASCM_PreSharedKey в RASCREDENTIALS. полеdwMask.

Заметка

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

Требования

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