RasEnumEntriesA 함수(ras.h)

  • 아티클

RasEnumEntries 함수는 원격 액세스 전화 번호부의 모든 항목 이름을 나열합니다.

구문

DWORD RasEnumEntriesA(
  [in]      LPCSTR          unnamedParam1,
  [in]      LPCSTR          unnamedParam2,
  [in, out] LPRASENTRYNAMEA unnamedParam3,
  [in, out] LPDWORD         unnamedParam4,
  [out]     LPDWORD         unnamedParam5
);

매개 변수

[in] unnamedParam1

예약; 은 NULL이어야 합니다.

[in] unnamedParam2

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

이 매개 변수가 NULL이면 AllUsers 프로필 및 사용자 프로필의 모든 원격 액세스 전화 번호부 파일에서 항목이 열거됩니다.

[in, out] unnamedParam3

출력 시 각 전화 번호부 항목에 대해 하나씩 RASENTRYNAME 구조의 배열을 수신하는 버퍼에 대한 포인터입니다.

입력 시 애플리케이션은 전달되는 구조체의 버전을 식별하기 위해 버퍼의 첫 번째 RASENTRYNAME 구조체의 dwSize 멤버를 sizeof(RASENTRYNAME)로 설정해야 합니다.

[in, out] unnamedParam4

입력 시 lprasentryname으로 지정된 버퍼의 크기(바이트)를 포함하는 변수에 대한 포인터입니다.

출력 시 전화 번호부 항목에 필요한 RASENTRYNAME 구조체 배열의 크기(바이트)를 포함하는 변수에 대한 포인터입니다.

Windows Vista 이상: 필요한 버퍼 크기를 확인하려면 lprasentryname이 NULL로 설정된 RasEnumEntries를 호출합니다. lpcb에서 가리키는 변수는 0으로 설정해야 합니다. 함수는 lpcb 에서 필요한 버퍼 크기와 ERROR_BUFFER_TOO_SMALL 오류 코드를 반환합니다.

[out] unnamedParam5

lprasentryname으로 지정된 버퍼에 기록된 전화 번호부 항목 수를 받는 변수에 대한 포인터입니다.

반환 값

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

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

값 의미
ERROR_BUFFER_TOO_SMALL
 lprasentryname 버퍼가 충분히 크지 않습니다. lpcb 매개 변수는 함수를 호출하기 전에 설정해야 하는 lprasentryname 매개 변수의 dwSize 멤버보다 작습니다. 함수는 lpcb가 가리키는 변수에 필요한 버퍼 크기를 반환합니다.

Windows Vista 이상: lprasentryname 버퍼는 NULL로 설정될 수 있으며 lpcb가 가리키는 변수는 0으로 설정될 수 있습니다. 함수는 lpcb가 가리키는 변수에 필요한 버퍼 크기를 반환합니다.
ERROR_INVALID_SIZE
 lprasentryname이 가리키는 RASENTRYNAME 구조체의 dwSize 값은 현재 플랫폼에서 지원되지 않는 구조체의 버전을 지정합니다. 예를 들어 Windows 95에서 RasEnumEntries 는 DwSize 가 RASENTRYNAME 에 dwFlags 및 szPhonebookPath 멤버가 포함되어 있음을 나타내는 경우 이 오류를 반환합니다. 이러한 멤버는 Windows 95에서 지원되지 않으므로(Windows 2000 이상에서만 지원됨)
ERROR_NOT_ENOUGH_MEMORY
 함수가 작업을 완료하기에 충분한 메모리를 할당할 수 없습니다.

설명

다음 샘플 코드는 Windows Vista 이상 버전의 Windows에서 RAS 전화 번호부 항목을 열거합니다. 이 코드는 처음에 RasEnumEntries 를 호출하여 전달할 버퍼의 크기를 가져옵니다. 그런 다음, 코드는 RasEnumEntries 를 다시 호출하여 항목을 열거합니다. 두 번째 호출의 경우 코드는 버퍼에서 첫 번째 RASENTRYNAME 구조체의 dwSize 멤버를 sizeof(RASENTRYNAME)로 설정하여 구조체 버전을 지정합니다.

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "raserror.h"
#pragma comment(lib, "rasapi32.lib")

DWORD __cdecl wmain(){

    DWORD dwCb = 0;
    DWORD dwRet = ERROR_SUCCESS;
    DWORD dwEntries = 0;
    LPRASENTRYNAME lpRasEntryName = NULL;
    
    // Call RasEnumEntries with lpRasEntryName = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS entry names.
        lpRasEntryName = (LPRASENTRYNAME) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasEntryName == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASENTRYNAME structure in the array must contain the structure size
        lpRasEntryName[0].dwSize = sizeof(RASENTRYNAME);
        
        // Call RasEnumEntries to enumerate all RAS entry names
        dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

        // If successful, print the RAS entry names 
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS entry names were found:\n");
            for (DWORD i = 0; i < dwEntries; i++){
                wprintf(L"%s\n", lpRasEntryName[i].szEntryName);
            }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasEntryName);
        lpRasEntryName = NULL;
        return 0;
    }

    // There was either a problem with RAS or there are RAS entry names to enumerate    
    if(dwEntries >= 1){
        wprintf(L"The operation failed to acquire the buffer size.\n");
    }else{
        wprintf(L"There were no RAS entry names found:.\n");
    }

    return 0;
}

참고

ras.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 RasEnumEntries를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항

요구 사항 값
지원되는 최소 클라이언트 Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버 Windows 2000 Server[데스크톱 앱만]
대상 플랫폼 Windows
헤더 ras.h
라이브러리 Rasapi32.lib
DLL Rasapi32.dll

추가 정보

RASENTRYNAME

RasEnumConnections

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

원격 액세스 서비스 함수