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

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

Синтаксис

DWORD RasGetCredentialsA(
  [in]      LPCSTR            unnamedParam1,
  [in]      LPCSTR            unnamedParam2,
  [in, out] LPRASCREDENTIALSA unnamedParam3
);

Параметры

[in] unnamedParam1

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

[in] unnamedParam2

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

[in, out] unnamedParam3

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

Для входных данных задайте для элемента dwSize структуры значение sizeof(RASCREDENTIALS) и задайте элемент dwMask, чтобы указать учетные данные для получения. Когда функция возвращается, dwMask указывает элементы, которые были успешно получены.

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

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

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

Замечания

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

Требования

См. также

RASCREDENTIALS

RasGetEntryDialParams

RasSetCredentials

Обзор службы удаленного доступа (RAS)

функции службы удаленного доступа