RasSetEntryDialParamsA 函数（ras.h）

项目
11/20/2024

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 为空字符串，fRemovePasswordFALSE，则密码将设置为空字符串。如果 fRemovePassword TRUE，则会删除 szUserName 指定的用户的此电话簿条目中存储的密码，而不考虑 szPassword 字符串的内容。 Windows NT 4.0：无论 szUserName 是否为空字符串，szPassword 指定的字符串都会更改密码。 Windows XP/2000：如果 szPassword 包含 RasGetCredentials 或 RasGetEntryDialParams返回的密码句柄，RasSetEntryDialParams 成功返回任何当前保存的密码。
szDomain	一个以 null 结尾的字符串，其中包含要登录的域的名称。如果 szDomain 为空字符串，则域名不会更改。
dwSubEntry	指定建立连接时要拨号的初始子项的（基于一个）索引。
dwCallbackId	指定 RAS 传递给 RasDialFunc2 回调函数的应用程序定义值。

[in] unnamedParam3

指定是否删除 lprasdialparams->szUserName指示的用户的电话簿条目的存储密码。如果 fRemovePasswordTRUE，则会删除密码。将 fRemovePassword 设置为 TRUE 相当于在拨号网络中选中“取消保存密码”复选框。设置电话簿条目的密码或其他属性时，请将 fRemovePassword 设置为 FALSE。

返回值

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

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

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

言论

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

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

注意

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

要求

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