RasDialA 함수(ras.h)

아티클
03/15/2023

RasDial 함수는 RAS 클라이언트와 RAS 서버 간에 RAS 연결을 설정합니다. 연결 데이터에는 콜백 및 사용자 인증 정보가 포함됩니다.

구문

DWORD RasDialA(
  [in]  LPRASDIALEXTENSIONS unnamedParam1,
  [in]  LPCSTR              unnamedParam2,
  [in]  LPRASDIALPARAMSA    unnamedParam3,
  [in]  DWORD               unnamedParam4,
  [in]  LPVOID              unnamedParam5,
  [out] LPHRASCONN          unnamedParam6
);

매개 변수

[in] unnamedParam1

사용하도록 설정할 RasDial 확장 기능 집합을 지정하는 RASDIALEXTENSIONS 구조체에 대한 포인터입니다. 이러한 기능을 사용하도록 설정할 필요가 없는 경우 이 매개 변수를 NULL 로 설정합니다.

[in] unnamedParam2

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

[in] unnamedParam3

RAS 연결에 대한 호출 매개 변수를 지정하는 RASDIALPARAMS 구조체에 대한 포인터입니다. RasGetEntryDialParams 함수를 사용하여 특정 전화 번호부 항목에 대해 이 구조체의 복사본을 검색합니다.

호출자는 전달되는 구조체의 버전을 식별하기 위해 RASDIALPARAMS 구조체의 dwSize 멤버를 sizeof(RASDIALPARAMS)로 설정해야 합니다.

RASDIALPARAMS 구조체의 szPhoneNumber 멤버가 빈 문자열인 경우 RasDial은 전화 번호부 항목에 저장된 전화 번호를 사용합니다.

[in] unnamedParam4

lpvNotifier 매개 변수의 특성을 지정합니다. lpvNotifier가 NULL이면 dwNotifierType이 무시됩니다. lpvNotifier가 NULL이 아닌 경우 dwNotifierType을 다음 값 중 하나로 설정합니다.

값	의미
0	lpvNotifier 매개 변수는 RasDialFunc 콜백 함수를 가리킵니다.
1	lpvNotifier 매개 변수는 RasDialFunc1 콜백 함수를 가리킵니다.
2	lpvNotifier 매개 변수는 RasDialFunc2 콜백 함수를 가리킵니다.

[in] unnamedParam5

RasDial 이벤트 알림을 받을 창 핸들 또는 RasDialFunc, RasDialFunc1 또는 RasDialFunc2 콜백 함수 를 지정합니다. dwNotifierType 매개 변수는 lpvNotifier의 특성을 지정합니다. 자세한 내용은 앞의 설명을 참조하세요.

이 매개 변수가 NULL이 아닌 경우 RasDial은 각 RasDial 이벤트에 대해 창을 메시지를 보내거나 콜백 함수 를 호출합니다 . 또한 RasDial 호출은 비동기적으로 작동합니다. RasDial 은 연결이 설정되기 전에 즉시 를 반환하고 창 또는 콜백 함수를 통해 진행 상황을 전달합니다.

lpvNotifier가 NULL이면 RasDial 호출이 동기적으로 작동합니다. 연결 시도가 성공적으로 완료되거나 실패할 때까지 RasDial이 반환되지 않습니다.

lpvNotifier가 NULL이 아닌 경우 RasDial에 대한 초기 호출 후 언제든지 창 또는 콜백 함수에 대한 알림이 발생할 수 있습니다. 알림은 다음 이벤트 중 하나가 발생하면 종료됩니다.

연결이 설정됩니다. 즉, RAS 연결 상태가 RASCS_Connected.
연결이 실패합니다. 즉, dwError 는 0이 아닌 값입니다.
RasHangUp 은 연결에서 호출됩니다.

콜백 알림은 RasDial에 대한 초기 호출 중에 캡처된 스레드의 컨텍스트에서 이루어집니다.

[out] unnamedParam6

HRASCONN 형식의 변수에 대한 포인터입니다. RasDial을 호출하기 전에 HRASCONN 변수를 NULL로 설정합니다. RasDial이 성공하면 RAS 연결에 대한 핸들을 *lphRasConn에 저장합니다.

반환 값

함수가 성공하면 반환 값이 ERROR_SUCCESS RAS 연결에 대한 핸들이 lphRasConn이 가리키는 변수에 반환됩니다.

함수가 실패하면 반환 값은 라우팅 및 원격 액세스 오류 코드 또는 Winerror.h에서 가져옵니다.

설명

즉시 반환된 후에 발생하는 오류는 RasGetConnectStatus에서 검색할 수 있습니다. 애플리케이션이 RasHangUp 을 호출하여 연결을 끊을 때까지 데이터를 사용할 수 있습니다.

애플리케이션은 NULL이 아닌 연결 핸들이 *lphRasConn에 저장되면 결국 RasHangUp을 호출해야 합니다. RasDial이 0이 아닌(오류) 값을 반환하는 경우에도 적용됩니다.

애플리케이션은 RasDial 알림 콜백 함수에서 RasHangUp을 안전하게 호출할 수 있습니다. 그러나 이 작업을 수행하면 루틴이 반환될 때까지 중단이 발생하지 않습니다.

lpRasDialExtensions가 가리키는 구조체가 RDEOPT_PausedStates 사용하도록 설정하면 RASCS_PAUSED 비트가 1로 설정된 상태가 될 때마다 RasDial 함수가 일시 중지됩니다. 이러한 일시 중지된 상태에서 RasDial을 다시 시작하려면 RasDial을 다시 호출하여 *lphRasConn의 원래 RasDial 호출에서 반환된 연결 핸들을 전달합니다. 일시 중지된 상태에서 다시 시작할 때 원래 RasDial 호출에 사용된 것과 동일한 알림이 사용되어야 합니다.

lpvNotifier 매개 변수는 진행률 알림 메시지를 수신하는 창에 대한 핸들입니다. 진행률 알림 메시지에서 wParam은 RasDialFunc 및 RasDialFunc1의 rasconnstate 매개 변수와 동일하며 lParam은 RasDialFunc 및 RasDialFunc1의 dwError 매개 변수와 동일합니다.

진행률 알림 메시지는 시스템 등록 메시지 코드를 사용합니다. 다음과 같이 이 메시지 코드의 값을 가져올 수 있습니다.

UINT unMsg = RegisterWindowMessageA( RASDIALEVENT );
if (unMsg == 0)
    unMsg = WM_RASDIALEVENT;

RAS는 참조된 연결을 지원합니다. 전화를 걸고 있는 항목이 이미 연결되어 있으면 RasDial 은 SUCCESS 를 반환하고 연결이 참조됩니다. 연결을 끊기 위해 연결의 각 RasDial 은 RasHangUp과 일치해야 합니다.

일부 전화 번호부 항목에는 인증을 위해 EAP(Extensible Authentication Protocol)가 필요하므로 호출자는 RasDial을 호출하기 전에 RasGetEapUserIdentity를 호출해야 합니다. RasGetEapUserIdentity가 ERROR_INVALID_FUNCTION_FOR_ENTRY 반환하는 경우 전화 번호부 항목에 EAP가 필요하지 않습니다. 그러나 RasGetEapUserIdentity가 NO_ERROR 반환하는 경우 호출자는 RasGetEapUserIdentity의 EAP ID 정보를 RASDIALEXTENSIONS의 RasEapInfo 멤버 및 RASDIALPARAMS의 szUserName 멤버로 복사해야 합니다. 자세한 내용은 RasGetEapUserIdentity 를 참조하세요. 전화 번호부 항목에 EAP가 필요한 경우 항목에 대한 RASENTRY 구조의 dwfOptions 멤버에 RASEO_RequireEAP 플래그가 포함됩니다.

RasDial이 RASCS_CallbackSetByCaller 상태를 입력하도록 지정하려면 RasDial에 대한 초기 호출에서 lpRasDialParams-szCallbackNumber>를 "*"로 설정합니다. 알림 처리기가 이 상태로 호출되면 콜백 번호를 사용자가 제공한 숫자로 설정합니다.

참고

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

요구 사항


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