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) |