rasDialA 函数 (ras.h)

项目
08/25/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
);

parameters

[in] unnamedParam1

指向 RASDIALEXTENSIONS 结构的指针，该结构指定要启用的 一组 RasDial 扩展功能。如果不需要启用这些功能，请将此参数设置为 NULL 。

[in] unnamedParam2

指向以 null 结尾的字符串的指针，该字符串指定电话簿 (PBK) 文件的完整路径和文件名。如果此参数为 NULL，则该函数使用当前默认的电话簿文件。默认电话簿文件是用户在“拨号网络”对话框的“用户首选项”属性表中选择的文件。

[in] unnamedParam3

指向 RASDIALPARAMS 结构的指针，该结构指定 RAS 连接的调用参数。使用 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

指定窗口句柄或 RasDialFunc、 RasDialFunc1 或 RasDialFunc2 回调函数以接收 RasDial 事件通知。 dwNotifierType 参数指定 lpvNotifier 的性质。有关更多详细信息，请参阅前面的说明。

如果此参数不为 NULL，则 RasDial 会为每个 RasDial 事件向窗口发送消息或调用回调函数。此外， RasDial 调用以异步方式运行： RasDial 在建立连接之前立即返回，并通过窗口或回调函数传达其进度。

如果 lpvNotifier 为 NULL， 则 RasDial 调用将同步运行： RasDial 在连接尝试成功完成或失败之前不会返回。

如果 lpvNotifier 不为 NULL，则初始调用 RasDial 后，随时可能会向窗口或回调函数发出通知。发生以下事件之一时，通知结束：

已建立连接。换句话说，RAS 连接状态RASCS_Connected。
连接失败。换句话说， dwError 是非零值。
在连接上调用 RasHangUp。

回调通知是在初始调用 RasDial 期间捕获的线程上下文中发出的。

[out] unnamedParam6

指向 类型为 HRASCONN 的变量的指针。在调用 RasDial 之前，将 HRASCONN 变量设置为 NULL。如果 RasDial 成功，它会将 RAS 连接的句柄存储到 *lphRasConn 中。

返回值

如果函数成功，则返回值 ERROR_SUCCESS ，并在 lphRasConn 指向的变量中返回 RAS 连接的句柄。

如果函数失败，则返回值为“ 路由和远程访问错误代码” 或“Winerror.h”。

注解

RasGetConnectStatus 可以检测到立即返回后发生的错误。数据可用，直到应用程序调用 RasHangUp 来挂起连接。

每当非 NULL 连接句柄存储到 *lphRasConn 中时，应用程序都必须最终调用 RasHangUp。即使 RasDial 返回非零 (错误) 值也是如此。

应用程序可以从 RasDial 通知器回调函数安全地调用 RasHangUp 。但是，如果完成此操作，则在例程返回之前不会发生挂起。

如果 lpRasDialExtensions 指向的结构启用了 RDEOPT_PausedStates，则 每当 RasDial 函数进入 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) 进行身份验证，因此调用方应在调用 RasDial 之前调用 RasGetEapUserIdentity。如果 RasGetEapUserIdentity 返回 ERROR_INVALID_FUNCTION_FOR_ENTRY，则电话簿条目不需要 EAP。但是，如果 RasGetEapUserIdentity 返回NO_ERROR，调用方应将 EAP 标识信息从 RasGetEapUserIdentity 复制到 RASDIALEXTENSIONS 的 RasEapInfo 成员和 RASDIALPARAMS 的 szUserName 成员中。有关详细信息 ，请参阅 RasGetEapUserIdentity 。如果电话簿条目需要 EAP，则条目的 RASENTRY 结构的 dwfOptions 成员包含 RASEO_RequireEAP 标志。

若要指定 RasDial 应进入RASCS_CallbackSetByCaller状态，请在初始调用 RasDial 时将 lpRasDialParams-szCallbackNumber> 设置为“*”。当使用此状态调用通知处理程序时，请将回调编号设置为用户提供的数字。

注意

ras.h 标头将 RasDial 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	ras.h
Library	Rasapi32.lib
DLL	Rasapi32.dll