Функция RasGetCredentialsA (ras.h)
Функция RasGetCredentials извлекает учетные данные пользователя, связанные с указанной записью телефонной книги RAS.
Синтаксис
DWORD RasGetCredentialsA(
[in] LPCSTR unnamedParam1,
[in] LPCSTR unnamedParam2,
[in, out] LPRASCREDENTIALSA unnamedParam3
);
Параметры
[in] unnamedParam1
Указатель на строку, завершающуюся null, которая указывает полный путь и имя файла телефонной книги (PBK). Если этот параметр имеет значение NULL, функция использует текущий файл телефонной книги по умолчанию. Файл телефонной книги по умолчанию — это файл, выбранный пользователем на странице свойств Пользовательские настройки диалогового окна Сеть с телефонным подключением .
[in] unnamedParam2
Указатель на строку с пустым завершением, указывающую имя записи телефонной книги.
[in, out] unnamedParam3
Указатель на структуру RASCREDENTIALS , которая в выходных данных получает учетные данные пользователя, связанные с указанной записью телефонной книги.
На входных данных задайте для элемента dwSize структуры значение sizeof(RASCREDENTIALS) и задайте член dwMask , чтобы указать учетные данные для извлечения. При возврате функции dwMask указывает элементы, которые были успешно извлечены.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение будет ERROR_SUCCESS.
Если функция завершается ошибкой, возвращается один из следующих кодов ошибок или значение из кода ошибок маршрутизации и удаленного доступа или Winerror.h.
| Значение | Значение |
|---|---|
|
Не удается найти указанную телефонную книгу. |
|
Указанная запись не существует в телефонной книге. |
|
Параметр lpCredentials имеет значение NULL. |
|
Член dwSize структуры RASCREDENTIALS является нераспознанным значением. |
Комментарии
Функция RasGetCredentials извлекает учетные данные последнего пользователя для подключения с помощью указанной записи телефонной книги или учетные данные, указанные впоследствии при вызове функции RasSetCredentials для записи телефонной книги.
Эта функция является предпочтительным способом безопасного получения учетных данных, связанных с записью телефонной книги RAS. RasGetCredentials заменяет функцию RasGetEntryDialParams , которая может не поддерживаться в будущих выпусках Windows.
RasGetCredentials не возвращает фактический пароль. Вместо этого член szPassword структуры RASCREDENTIALS содержит дескриптор сохраненного пароля. Замените этот дескриптор сохраненным паролем в последующих вызовах RasSetCredentials и RasDial. При появлении этого дескриптора RasDial извлекает и использует сохраненный пароль. Значение этого дескриптора может измениться в будущих версиях операционной системы; не разрабатывать код, зависящий от содержимого или формата этого значения.
Член dwMaskrasCREDENTIALS содержит флаг RASCM_Password, если система сохранила пароль для указанной записи. Если в системе нет сохраненного пароля для этой записи, dwMask не содержит RASCM_Password.
Windows 2000/NT: Эта функция не поддерживается.
Если dwMask структуры RASCREDENTIALS содержит флаг RASCM_DefaultCreds, возвращаемые учетные данные являются учетными данными по умолчанию для подключения ко всем пользователям.
Чтобы получить общий ключ, используйте флаг RASCM_PreSharedKey в поле RASCREDENTIALS.dwMask.
Windows 2000/NT: Эта функция не поддерживается.
Следующий пример кода создает запись телефонной книги RasEntryName, задает ее учетные данные с помощью RasSetCredentials, а затем извлекает эти учетные данные с помощью RasGetCredentials.
#include <windows.h>
#include "ras.h"
#include <stdio.h>
#include <tchar.h>
#include "strsafe.h"
#define PHONE_NUMBER_LENGTH 7
#define DEVICE_NAME_LENGTH 5
#define DEVICE_TYPE_LENGTH 5
#define DOMAIN_NAME_LENGTH 9
#define USER_NAME_LENGTH 11
DWORD __cdecl wmain(){
DWORD dwRet = ERROR_SUCCESS;
LPTSTR lpszEntry = L"RasEntryName";
LPTSTR lpszPhoneNumber = L"5555555";
LPTSTR lpszDeviceName = L"Modem";
LPTSTR lpszDeviceType = RASDT_Modem;
LPTSTR lpszDomainName = L"RASDomain";
LPTSTR lpszUserName = L"RASUserName";
/***********************************************************************************************/
// Create a new phone book entry
/***********************************************************************************************/
// Allocate heap memory for the RASENTRY structure
LPRASENTRY lpentry = (LPRASENTRY)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRY));
if (lpentry == NULL){
wprintf(L"HeapAlloc failed!\n");
return 0;
}
// The RASENTRY->dwSize member has to be initialized or the RRAS RasValidateEntryName() and
// RasSetEntryProperties APIs will fail below.
lpentry->dwSize = sizeof(RASENTRY);
lpentry->dwFramingProtocol = RASFP_Ppp;
lpentry->dwfOptions = 0;
lpentry->dwType = RASFP_Ppp;
dwRet |= StringCchCopyN(lpentry->szLocalPhoneNumber, RAS_MaxPhoneNumber, lpszPhoneNumber, PHONE_NUMBER_LENGTH);
dwRet |= StringCchCopyN(lpentry->szDeviceName, RAS_MaxDeviceName, lpszDeviceName, DEVICE_NAME_LENGTH);
dwRet |= StringCchCopyN(lpentry->szDeviceType, RAS_MaxDeviceType, lpszDeviceType, DEVICE_TYPE_LENGTH);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASENTRY structure initialization failed!\n");
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Validate the new entry's name
dwRet = RasValidateEntryName(NULL, lpszEntry);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasValidateEntryName failed: Error = %d\n", dwRet);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Create and set the new entry's properties
dwRet = RasSetEntryProperties(NULL, lpszEntry, lpentry, lpentry->dwSize, NULL, 0);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasSetEntryProperties failed: Error = %d\n", dwRet);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
/******************************************************************************************/
// Set and get the new entry's credentials
/******************************************************************************************/
// Allocate heap memory for the RASCREDENTIALS structure
LPRASCREDENTIALS lpCred = (LPRASCREDENTIALS) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASCREDENTIALS));
if (lpCred == NULL){
wprintf(L"HeapAlloc failed!\n");
return 0;
}
// The RASCREDENTIALS->dwsize member must be initialized or the RRAS RasSetCredentials() and
// RasGetCredentials() APIs will fail below
lpCred->dwSize = sizeof(RASCREDENTIALS);
// The entry's credentials must first be set with RasSetCredentials() before they can be
// retrieved with RasGetCredentials(). The values below are used to set the new entry's credentials.
dwRet |= StringCchCopyN(lpCred->szDomain, DNLEN, lpszDomainName, DOMAIN_NAME_LENGTH);
dwRet |= StringCchCopyN(lpCred->szUserName, UNLEN, lpszUserName, USER_NAME_LENGTH);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASCREDENTIALS structure initialization failed!\n");
HeapFree(GetProcessHeap(), 0, lpCred);
return 0;
}
// The username, password, and Domain credentials are valid
lpCred->dwMask = RASCM_UserName | RASCM_Password | RASCM_Domain;
// Set the newly created entry's credentials
dwRet = RasSetCredentials(NULL, lpszEntry, lpCred, FALSE);
// The same RASCREDENTIALS structure is used to 'set' and 'get' the credentials. Therefore, zero out
// its values. (this proves RasGetCredentials works below!)
dwRet |= StringCchCopyN(lpCred->szDomain, DNLEN, L"", 0);
dwRet |= StringCchCopyN(lpCred->szUserName, UNLEN, L"", 0);
dwRet |= StringCchCopyN(lpCred->szPassword, UNLEN, L"", 0);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASCREDENTIALS structure reset failed!\n");
HeapFree(GetProcessHeap(), 0, lpCred);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Grab the newly created entry's credentials
dwRet = RasGetCredentials(NULL, lpszEntry, lpCred);
if(dwRet == ERROR_SUCCESS){
wprintf(L"The following credentials were retrieved for the entry: %s\n\tUser name: %s\n\tPassword: %s\n\tDomain: %s\n", lpszEntry, lpCred->szUserName, lpCred->szPassword, lpCred->szDomain);
}else{
wprintf(L"RasValidateEntryName failed: Error = %d\n", dwRet);
}
// Clean up: delete the new entry
dwRet = RasDeleteEntry(NULL, lpszEntry);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasDeleteEntry failed: Error = %d\n", dwRet);
}
HeapFree(GetProcessHeap(), 0, lpentry);
HeapFree(GetProcessHeap(), 0, lpCred);
return 0;
}
Примечание
Заголовок ras.h определяет RasGetCredentials как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | ras.h |
| Библиотека | Rasapi32.lib |
| DLL | Rasapi32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по