RasSetCredentials

DWORD RasSetCredentials(  _In_ LPCTSTR          lpszPhonebook,  _In_ LPCTSTR          lpszEntry,  _In_ LPRASCREDENTIALS lpCredentials,  _In_ BOOL             fClearCredentials);

说明

该函数用于为某个RAS电话簿入口设置用户凭证。

参数

lpszPhonebook [in]

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

lpszEntry [in]

指定电话簿条目名称。

lpCredentials [in]

指向一个包含用户凭证的RASCREDENTIALS结构。调用前将结构中的dwSize设置为sizeof(RASCREDENTIALS)，dwMask成员用于指示要设置的凭证信息。

fClearCredentials [in]

该参数用于指示是否将已存在的凭证设置为空串以清除凭证。为TRUE时由RASCREDENTIALS结构中的dwMask成员指定清除哪个凭证。为FALSE时设置新的凭证。

返回值

成功时返回ERROR_SUCCESS。
失败时返回以下列表中的值之一或来自Routing and Remote Access Error Codes或Winerror.h中定义的错误码。

值 含义 ERROR_CANNOT_OPEN_PHONEBOOK 找不到电话簿。 ERROR_INVALID_PARAMETER lpCredentials参数为NULL或者指定的电话簿条目不存在。 ERROR_ACCESS_DENIED 以下情况返回该错误： 1.应用程序尝试为一个单独的用户连接设置默认的凭证。默认凭证只能设置给所有用户。2.只有管理员才有权限为所有用户设置预共享密钥或凭证。

注意事项

该函数用于设置与RAS电话簿条目关联的用户凭证。该凭证要么是与用户最后一次成功拨号所使用的条目关联的凭证，要么是调用RasSetCredentials或RasSetEntryDialParams函数设置的凭证。该函数是安全存储一个条目关联凭证的优先推荐方法。RasSetEntryDialParams函数则不建议使用，因为后期版本的Windows系统可能不再支持该方法。调用RasGetCredentials函数取回的密码文本是16个*字符，出于安全原因不会返回明文。再调用RasGetCredentials或RasGetEntryDialParams设置凭证时，如果RASCREDENTIALS结构中的成员szPassword保持16个*字符，则密码不会被更改。设置凭证时如果设置RASCREDENTIALS结构中的成员dwMask包含RASCM_DefaultCreds标记位，则可以为所有用户连接设置一个默认凭证。不允许为单独用户连接设置默认凭证。设置所有用户连接的默认凭证时，如果lpszPhonebook参数不为空，那么电话簿文件必须在所有用户应用程序数据目录下。通过调用SHGetFolderPath函数并且设置其CSIDL参数的值为CSIDL_COMMON_APPDATA可以获取所有用户的应用程序数据目录。返回的目录再附加上该串即是正确的电话簿文件路径：\Microsoft\Network\Connections\Pbk。

注意 lpszPhonebook参数在后续版本的Windows操作系统中可能不再被支持，只需要传入NULL即可。

设置RASCREDENTIALS.dwMask成员包含RASCM_PreSharedKey标记可以设置一个预共享密钥。

系统支持

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