RasSetCredentialsA 函数（ras.h）

项目
11/20/2024

RasSetCredentials 函数设置与指定的 RAS 电话簿条目关联的用户凭据。

语法

DWORD RasSetCredentialsA(
  [in] LPCSTR            unnamedParam1,
  [in] LPCSTR            unnamedParam2,
  [in] LPRASCREDENTIALSA unnamedParam3,
  [in] BOOL              unnamedParam4
);

参数

[in] unnamedParam1

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

[in] unnamedParam2

指向以 null 结尾的字符串的指针，该字符串指定电话簿条目的名称。

[in] unnamedParam3

指向 RASCREDENTIALS 结构的指针，该结构指定要为指定的电话簿条目设置的用户凭据。在调用 RasSetCredentials之前，请将结构的 dwSize 成员设置为 sizeof(RASCREDENTIALS)，并将 dwMask 成员设置为指示要设置的凭据信息。

[in] unnamedParam4

一个值，该值指定是否 RasSetCredentials 通过将现有凭据设置为空字符串“”来清除现有凭据。如果此标志 TRUE，则 dwMaskRASCREDENTIALS 结构的成员指示函数设置为空字符串的凭据。如果此标志 FALSE，则函数会根据相应 RASCREDENTIALS 成员的内容设置指示的凭据。

返回值

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

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

价值	意义
ERROR_CANNOT_OPEN_PHONEBOOK	找不到指定的电话簿。
ERROR_INVALID_PARAMETER	lpCredentials 参数 NULL，或者电话簿中不存在指定的条目。
ERROR_ACCESS_DENIED	出现以下情况之一：调用应用程序尝试为每个用户连接设置默认凭据。只能为所有用户连接设置默认凭据。如果用户没有为所有用户设置预共享密钥或凭据的正确特权，以防出现所有用户 connectoid。只有管理员才能完成这些任务。

言论

RasSetCredentials 函数设置与指定的 RAS 电话簿条目关联的用户凭据。使用电话簿条目存储的凭据是最后一个用户使用指定的电话簿条目成功连接的凭据，或者随后在呼叫 RasSetCredentials 或 RasSetEntryDialParams 函数中为电话簿条目指定的凭据。

RasSetCredentials 函数是使用电话簿条目安全地存储凭据的首选方法。 RasSetCredentials 取代 RasSetEntryDialParams 函数，在 Windows 操作系统的未来版本中可能不支持此功能。

密码句柄为“****************”（16 个星号）。如果调用 RasGetCredentials 并在密码字段中收到 16 *s 的回发，则存在存储的密码，出于安全原因，不会以纯文本形式返回该密码。如果 szPasswordRASCREDENTIALS 结构的成员包含 RasGetCredentials 或 RasGetEntryDialParams返回的密码句柄（16 *s），则对 RasSetCredentials 的下一次调用将不会更改保存的密码。

若要设置所有用户连接的默认凭据，请将 dwMask 成员中的 RASCM_DefaultCreds 标志设置为 RASCREDENTIALS 结构 lpCredentials 参数所指向。如果尝试为每用户连接设置默认凭据，RasSetCredentials 返回 ERROR_ACCESS_DENIED。

为所有用户连接设置凭据时，如果呼叫应用程序为电话簿参数指定非 NULL 值，lpszPhonebook，则电话簿文件必须位于所有用户应用程序数据路径下的电话簿目录中。若要获取电话簿文件的正确位置，请首先调用 SHGetFolderPath，CSIDL 值为 CSIDL_COMMON_APPDATA。 SHGetFolderPath 返回所有用户应用程序数据路径。将以下字符串追加到此路径：

Microsoft\Network\Connections\Pbk

组合路径是电话簿文件的正确位置。

注释指定 lpszPhonebook 参数的非 NULL 值在更高版本的 Windows 操作系统中可能不受支持。

若要设置预共享密钥，请使用 RASCREDENTIALS中的 RASCM_PreSharedKey 标志。dwMask 字段。

注意

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

要求

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