RasSetEntryDialParamsA 函数 (ras.h)

项目
08/25/2023

RasSetEntryDialParams 函数更改上次成功调用 RasDial 或 RasSetEntryDialParams 函数时为指定的电话簿条目保存的连接信息。

语法

DWORD RasSetEntryDialParamsA(
  [in] LPCSTR           unnamedParam1,
  [in] LPRASDIALPARAMSA unnamedParam2,
  [in] BOOL             unnamedParam3
);

参数

[in] unnamedParam1

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

Windows Me/98/95： 此参数应始终为 NULL。拨号网络将电话簿条目存储在注册表中，而不是存储在电话簿文件中。

[in] unnamedParam2

指向 RASDIALPARAMS 结构的指针，该结构指定要与电话簿条目关联的连接参数。 RasSetEntryDialParams 使用结构的成员，如下所示。

成员	含义
dwSize	必须指定 (RASDIALPARAMS) 的大小，以标识结构的版本。
szEntryName	一个以 null 结尾的字符串，用于标识要为其设置参数的电话簿条目。
szPhoneNumber	未使用。设置为 NULL。
szCallbackNumber	包含回调电话号码的以 null 结尾的字符串。如果 szCallbackNumber 是空字符串 (“”) ，则不会更改回调编号。
szUserName	一个以 null 结尾的字符串，包含与此条目关联的用户的登录名。如果 szUserName 是空字符串，则不会更改用户名。
szPassword	一个以 null 结尾的字符串，包含 szUserName 指定的用户的密码。如果 szUserName 为空字符串，则不会更改密码。如果 szPassword 为空字符串，而 fRemovePassword 为 FALSE，则密码设置为空字符串。如果 fRemovePassword 为 TRUE，则无论 szPassword 字符串的内容如何，都将删除 szUserName 指定的用户的电话簿条目中存储的密码。 Windows NT 4.0：无论 szUserName 是否为空字符串，密码都会更改为 szPassword 指定的字符串。 Windows XP/2000：如果 szPassword 包含 RasGetCredentials 或 RasGetEntryDialParams 返回的密码句柄，则 RasSetEntryDialParams 将成功返回，而不会更改任何当前保存的密码。
szDomain	一个以 null 结尾的字符串，包含要登录的域的名称。如果 szDomain 是空字符串，则域名不会更改。
dwSubEntry	指定要在建立连接时要拨号的初始子项的 (从 1 开始的) 索引。
dwCallbackId	指定 RAS 传递给 RasDialFunc2 回调函数的应用程序定义值。

[in] unnamedParam3

指定是否删除 lprasdialparams-szUserName> 指示的用户的电话簿条目的存储密码。如果 fRemovePassword 为 TRUE，则删除密码。将 fRemovePassword 设置为 TRUE 等效于选中 Dial-Up Networking 中的“取消保存密码”检查框。设置电话簿条目的密码或其他属性时，请将 fRemovePassword 设置为 FALSE。

返回值

如果函数成功，则返回值 ERROR_SUCCESS。

如果函数失败，则返回值为以下错误代码之一，或者来自路由和远程访问错误代码或 Winerror.h 的值。

值	说明
ERROR_BUFFER_INVALID	由 lprasdialparams 指定的地址或缓冲区无效。
ERROR_CANNOT_OPEN_PHONEBOOK	电话簿已损坏或缺少组件。
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	电话簿条目不存在。

注解

若要创建新的电话簿条目，请使用 RasSetEntryProperties 函数。

Windows XP 或更高版本： 请勿使用 RasSetEntryDialParams 函数。若要设置电话簿条目的凭据，请使用 RasSetCredentials 函数。在作为参数传递给 RasDial 函数的 RASDIALPARAMS 结构中直接设置 RASDIALPARAMS (例如 szCallbackNumber、dwSubEntry 或 dwCallback) Id 的非凭据成员。

注意

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

要求

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