RasGetCredentialsA 함수(ras.h)

아티클
08/25/2023

RasGetCredentials 함수는 지정된 RAS 전화 번호부 항목과 연결된 사용자 자격 증명을 검색합니다.

구문

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

매개 변수

[in] unnamedParam1

전화 번호부(PBK) 파일의 전체 경로 및 파일 이름을 지정하는 null로 끝나는 문자열에 대한 포인터입니다. 이 매개 변수가 NULL인 경우 함수는 현재 기본 전화 번호부 파일을 사용합니다. 기본 전화 번호부 파일은 전화 접속 네트워킹 대화 상자의 사용자 기본 설정 속성 시트에서 사용자가 선택한 파일입니다.

[in] unnamedParam2

전화 번호부 항목의 이름을 지정하는 null로 끝나는 문자열에 대한 포인터입니다.

[in, out] unnamedParam3

출력 시 지정된 전화 번호부 항목과 연결된 사용자 자격 증명을 수신하는 RASCREDENTIALS 구조체에 대한 포인터입니다.

입력 시 구조체의 dwSize 멤버를 sizeof(RASCREDENTIALS)로 설정하고 dwMask 멤버를 설정하여 검색할 자격 증명 정보를 나타냅니다. 함수가 반환되면 dwMask 는 성공적으로 검색된 멤버를 나타냅니다.

반환 값

함수가 성공하면 반환 값이 ERROR_SUCCESS.

함수가 실패하면 반환 값은 다음 오류 코드 중 하나이거나 라우팅 및 원격 액세스 오류 코드 또는 Winerror.h의 값입니다.

값	의미
ERROR_CANNOT_OPEN_PHONEBOOK	지정된 전화 번호부를 찾을 수 없습니다.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	지정된 항목이 전화 번호부에 없습니다.
ERROR_INVALID_PARAMETER	lpCredentials 매개 변수는 NULL입니다.
ERROR_INVALID_SIZE	RASCREDENTIALS 구조체의 dwSize 멤버는 인식할 수 없는 값입니다.

설명

RasGetCredentials 함수는 지정된 전화 번호부 항목을 사용하여 연결하기 위해 마지막 사용자의 자격 증명 또는 전화 번호부 항목에 대한 RasSetCredentials 함수 호출에서 이후에 지정된 자격 증명을 검색합니다.

이 함수는 RAS 전화 번호부 항목과 연결된 자격 증명을 안전하게 검색하는 기본 방법입니다. RasGetCredentials 는 향후 Windows 릴리스에서 지원되지 않을 수 있는 RasGetEntryDialParams 함수를 대체합니다.

RasGetCredentials 는 실제 암호를 반환하지 않습니다. 대신 RASCREDENTIALS 구조체의 szPassword 멤버에는 저장된 암호에 대한 핸들이 포함됩니다. RasSetCredentials 및 RasDial에 대한 후속 호출에서 저장된 암호로 이 핸들을 대체합니다. 이 핸들이 표시되면 RasDial 은 저장된 암호를 검색하고 사용합니다. 이 핸들의 값은 이후 버전의 운영 체제에서 변경될 수 있습니다. 이 값의 내용이나 형식에 따라 달라지는 코드를 개발하지 마세요.

시스템이 지정된 항목에 대한 암호를 저장한 경우 RASCREDENTIALS의 dwMask 멤버에는 RASCM_Password 플래그가 포함됩니다. 시스템에 이 항목에 대해 저장된 암호가 없는 경우 dwMask 에는 RASCM_Password 포함되지 않습니다.

Windows 2000/NT: 이 기능은 지원되지 않습니다.

RASCREDENTIALS 구조의 dwMask에 RASCM_DefaultCreds 플래그가 포함된 경우 반환되는 자격 증명은 모든 사용자 연결에 대한 기본 자격 증명입니다.

미리 공유된 키를 검색하려면 RASCREDENTIALS.dwMask 필드에서 RASCM_PreSharedKey 플래그를 사용합니다.

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
헤더	ras.h
라이브러리	Rasapi32.lib
DLL	Rasapi32.dll

추가 정보

RASCREDENTIALS

RasGetEntryDialParams

RasSetCredentials

RAS(원격 액세스 서비스) 개요

원격 액세스 서비스 함수

RasGetCredentialsA 함수(ras.h)

구문

매개 변수

반환 값

설명

요구 사항

추가 정보

피드백

피드백

추가 리소스