RasDial

DWORD RasDial(
  _In_  LPRASDIALEXTENSIONS lpRasDialExtensions,
  _In_  LPCTSTR             lpszPhonebook,
  _In_  LPRASDIALPARAMS     lpRasDialParams,
  _In_  DWORD               dwNotifierType,
  _In_  LPVOID              lpvNotifier,
  _Out_ LPHRASCONN          lphRasConn
);

说明

用于建立一条从RAS客户端到RAS服务端之间的连接。连接数据包含了用户认证信息和回调数据。

参数

lpRasDialExtensions [in]

该指针指向一个 RASDIALEXTENSIONS 结构，用于指定一系列扩展功能。该参数可以为NULL。

lpszPhonebook [in]

指向一个包含完整路径的电话簿文件(PBK)。如果参数为空，则该函数使用默认的电话簿文件。默认的电话簿文件由用户在拨号网络对话框的[user preferences]属性窗口中选择。

lpRasDialParams [in]

指向一个包含RAS连接相关参数的RASDIALPARAMS结构。可以通过RASDIALPARAMS函数获取一个特定的电话簿条目的连接参数信息。

调用者必须设置RASDIALPARAMS结构的dwSize成员值为sizoef(RASDIALPARAMS)，用于识别结构的版本。

如果RASDIALPARAMS中的szPhoneNumber成员为空，该函数将使用电话簿条目中存储的号码进行拨号。

dwNotifierType [in]

指定lpvNotifier参数的类型。lpvNotifier为空时忽略该参数。类型应为以下列表中的值之一：

值	含义
0	lpvNotifier 指向一个RasDialFunc回调函数。
1	lpvNotifier 指向一个RasDialFunc1回调函数。
2	lpvNotifier 指向一个RasDialFunc2回调函数。

lpvNotifier [in]

指定一个用于接收RasDial通知消息的窗口句柄，或者是RasDialFunc、RasDialFunc1、RasDialFunc2回调函数。由dwNotifierType参数指定该参数的类型。查看该参数的描述以了解更多细节。

该参数不为空时，每个RasDial事件都会向窗口句柄发送消息，或者调用回调函数。另外，RasDial属于异步调用：该函数在连接建立前就会返回，然后通过向窗口句柄发消息或者调用回调函数的方式传达连接进度。

如果该参数为空，则RasDial在连接完成前不会返回。

如果该参数为这空，一旦RasDial返回，则可能在任何时候收到通知。以下条件满足后不会再收到通知：

• 连接已建立，换言之，RAS连接状态是 RASCS_Connected。
• 连接失败，或者dwError非零。

• 在连接上面调用了RasHangUp 函数。

  在首次调用RasDial时捕获的通知在一个线程上下文中生成。
  The callback notifications are made in the context of a thread captured during the initial call to RasDial.

lphRasConn [out]

指向HRASCONN类型，调用该函数前设置指针指向的内容为NULL。当连接成功建立时，指针指向连接句柄。

返回值

成功时返回ERROR_SUCCESS，并且lphRasConn 指向连接句柄。失败时返回来自Routing and Remote Access Error Codes或Winerror.h中定义的错误码。

注意事项

函数返回后可通过RasGetConnectStatus函数检查是否有错误发生。在调用RasHungup函数之前数据一直有效。

即便该函数返回失败，如果lphRasConn 指向的连接句柄不为空，则最终需要调用 RasHangUp 挂起该连接。

应用程序可以在该函数的回调通知中安全的调用RasHungUp，然而在程序返回前连接不会被挂起。

（我估计是在回调函数调用了RasHungUp之后，回调函数返回前没有真正挂起）

如果lpRasDialExtensions指向的结构中设置了RDEOPT_PausedStates标志，当进入RASCS_PAUSED状态时RasDial将暂停操作。使用上次调用RasDial返回的连接句柄再次调用RasDial函数调用可取消暂停状态，另外不能改变原先使用的通知参数和类型。

lpvNotifier参数是一个用于接收连接进度通知的窗口句柄。收到一个进度通知消息时，wParam参数与RasDialFunc和RasDialFunc1函数的rasconnstate参数相同，lParam参数与RasDialFunc和RasDialFunc1函数的dwError参数相同。

进度通知消息是一个由系统注册的全局消息代码。通过以下方式获得：

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

RAS支持引用连接。当拨号条目已经建立连接时，RasDial返回成功，并且直接引用此连接句柄。需要多次调用RasHungUp直到引用计数为零时才会断开连接。

某些电话簿条目需要EAP(Extensible Authentication Protocol)协议进行认证，因而在调用RasDial之前需要调用RasGetEapUserIdentity函数。

如果该函数返回ERROR_INVALID_FUNCTION_FOR_ENTRY，则该条目不要求EAP协议认证。

如果该函数返回NO_ERROR，调用RasDial之前应将该函数返回的RASEAPUSERIDENTITY结构中的dwSizeofEapInfo和pbEapInfo复制到lpRasDialExtensions参数指向的RASDIALEXTENSIONS成员RasEapInfo中，同时将RASEAPUSERIDENTITY结构中的szUserName复制到lpRasDialParams参数指向的RASDIALPARAMS中的szUserName成员。

如果电话簿条目要求EAP认证，那么RASENTRY结构中的dwfOptions包含RASEO_RequireEAP标记。

为了让RasDial进入RASCS_CallbackSetByCaller状态，首次调用 RasDial时将lpRasDialParams->szCallbackNumber设置为"*"。在此状态下收到通知时，用户需要提供一个呼叫号码。

系统支持

客户端最小支持	Windows 2000专业版
服务端最小支持	Windows 2000 Server
Header	Ras.h
Library	Rasapi32.lib
DLL	Rasapi32.dll
Unicode和ANSI名称	RasDialW(Unicode)和RasDialA(ANSI)