DWORD RasGetCredentials(
_In_ LPCTSTR lpszPhonebook,
_In_ LPCTSTR lpszEntry,
_Inout_ LPRASCREDENTIALS lpCredentials
);
说明
该函数用于获取与指定RAS电话簿条目关联的用户凭证。
参数
lpszPhonebook [in]
指向一个包含完整路径的电话簿文件(PBK)。如果参数为空,则该函数使用默认的电话簿文件。默认的电话簿文件由用户在拨号网络对话框的[user preferences]属性窗口中选择。
lpszEntry [in]
指定电话簿条目名称。
lpCredentials [in, out]
指向用于接收用户凭证的RASCREDENTIALS结构。调用前将RASCREDENTIALS结构中的成员dwSize设置为sizeof(RASCREDENTIALS),设置成员dwMask以指示需要取出的凭证信息。函数返回时,dwMask成员指示成功获取的凭证信息。
返回值
成功时返回ERROR_SUCCESS。
失败时返回以下列表中的值之一或来自Routing and Remote Access Error Codes或Winerror.h中定义的错误码。
值 | 含义 |
---|---|
ERROR_CANNOT_OPEN_PHONEBOOK | 找不到指定电话簿。 |
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY | 指定的电话簿条目找不到。 |
ERROR_INVALID_PARAMETER | lpCredentials参数为空。 |
ERROR_INVALID_SIZE | RASCREDENTIALS结构中的成员dwSize的值不正确。 |
注意事项
该函数用于获取与RAS电话簿条目关联的用户凭证。该凭证要么是与用户最后一次成功拨号所使用的条目关联的凭证,要么是调用RasSetCredentials或RasSetEntryDialParams函数设置的凭证。
该函数是安全获取一个条目关联凭证的优先推荐方法。RasGetEntryDialParams函数则不建议使用,因为后期版本的Windows系统可能不再支持该方法。
调用RasGetCredentials函数取回的密码文本是16个字符,出于安全原因不会返回明文。再调用RasGetCredentials或RasGetEntryDialParams设置凭证时,如果RASCREDENTIALS结构中的成员szPassword保持16个字符,则密码不会被更改。
设置凭证时如果设置RASCREDENTIALS结构中的成员dwMask包含RASCM_DefaultCreds标记位,则可以为所有用户连接设置一个默认凭证。不允许为单独用户连接设置默认凭证。
该函数不会返回凭证的明文密码,而是RASCREDENTIALS结构成员szPassword包含一个句柄,后续调用RasDial函数或RasSetCredentials函数时使用该句柄代替密码。RasDial函数会根据该句柄获取用户实际密码。不要开发依赖于此句柄内容或格式的代码,因为该够本的值在后续版本中可能会发生变化。
如果指定条目保存了密码,那么RASCREDENTIALS.dwMask包含RASCM_Password标志位。Windows 2000/NT版本不支持该特征。
如果RASCREDENTIALS.dwMask包含RASCM_DefaultCreds标志位,那么返回的是所有用户连接的缺省凭证。
设置RASCREDENTIALS.dwMask包含RASCM_PreSharedKey以获取预共享密钥。Windows 2000/NT版本不支持该特征。
以下示例代码创建一个名称为”RasEntryName”的条目,使用RasSetCredentials函数为该条目设置凭证,最后通过RasGetCredentials获取凭证。
#include <windows.h>
#include "ras.h"
#include <stdio.h>
#include <tchar.h>
#include "strsafe.h"
#define PHONE_NUMBER_LENGTH 7
#define DEVICE_NAME_LENGTH 5
#define DEVICE_TYPE_LENGTH 5
#define DOMAIN_NAME_LENGTH 9
#define USER_NAME_LENGTH 11
DWORD __cdecl wmain(){
DWORD dwRet = ERROR_SUCCESS;
LPTSTR lpszEntry = L"RasEntryName";
LPTSTR lpszPhoneNumber = L"5555555";
LPTSTR lpszDeviceName = L"Modem";
LPTSTR lpszDeviceType = RASDT_Modem;
LPTSTR lpszDomainName = L"RASDomain";
LPTSTR lpszUserName = L"RASUserName";
/***********************************************************************************************/
// Create a new phone book entry
/***********************************************************************************************/
// Allocate heap memory for the RASENTRY structure
LPRASENTRY lpentry = (LPRASENTRY)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRY));
if (lpentry == NULL){
wprintf(L"HeapAlloc failed!\n");
return 0;
}
// The RASENTRY->dwSize member has to be initialized or the RRAS RasValidateEntryName() and
// RasSetEntryProperties APIs will fail below.
lpentry->dwSize = sizeof(RASENTRY);
lpentry->dwFramingProtocol = RASFP_Ppp;
lpentry->dwfOptions = 0;
lpentry->dwType = RASFP_Ppp;
dwRet |= StringCchCopyN(lpentry->szLocalPhoneNumber, RAS_MaxPhoneNumber, lpszPhoneNumber, PHONE_NUMBER_LENGTH);
dwRet |= StringCchCopyN(lpentry->szDeviceName, RAS_MaxDeviceName, lpszDeviceName, DEVICE_NAME_LENGTH);
dwRet |= StringCchCopyN(lpentry->szDeviceType, RAS_MaxDeviceType, lpszDeviceType, DEVICE_TYPE_LENGTH);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASENTRY structure initilization failed!\n");
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Validate the new entry's name
dwRet = RasValidateEntryName(NULL, lpszEntry);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasValidateEntryName failed: Error = %d\n", dwRet);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Create and set the new entry's properties
dwRet = RasSetEntryProperties(NULL, lpszEntry, lpentry, lpentry->dwSize, NULL, 0);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasSetEntryProperties failed: Error = %d\n", dwRet);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
/******************************************************************************************/
// Set and get the new entry's credentials
/******************************************************************************************/
// Allocate heap memory for the RASCREDENTIALS structure
LPRASCREDENTIALS lpCred = (LPRASCREDENTIALS) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASCREDENTIALS));
if (lpCred == NULL){
wprintf(L"HeapAlloc failed!\n");
return 0;
}
// The RASCREDENTIALS->dwsize member must be initialized or the RRAS RasSetCredentials() and
// RasGetCredentials() APIs will fail below
lpCred->dwSize = sizeof(RASCREDENTIALS);
// The entry's credentials must first be set with RasSetCredentials() before they can be
// retrieved with RasGetCredentials(). The values below are used to set the new entry's credentials.
dwRet |= StringCchCopyN(lpCred->szDomain, DNLEN, lpszDomainName, DOMAIN_NAME_LENGTH);
dwRet |= StringCchCopyN(lpCred->szUserName, UNLEN, lpszUserName, USER_NAME_LENGTH);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASCREDENTIALS structure initilization failed!\n");
HeapFree(GetProcessHeap(), 0, lpCred);
return 0;
}
// The username, password, and Domain credentials are valid
lpCred->dwMask = RASCM_UserName | RASCM_Password | RASCM_Domain;
// Set the newly created entry's credentials
dwRet = RasSetCredentials(NULL, lpszEntry, lpCred, FALSE);
// The same RASCREDENTIALS structure is used to 'set' and 'get' the credentials. Therefore, zero out
// its values. (this proves RasGetCredentials works below!)
dwRet |= StringCchCopyN(lpCred->szDomain, DNLEN, L"", 0);
dwRet |= StringCchCopyN(lpCred->szUserName, UNLEN, L"", 0);
dwRet |= StringCchCopyN(lpCred->szPassword, UNLEN, L"", 0);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASCREDENTIALS structure reset failed!\n");
HeapFree(GetProcessHeap(), 0, lpCred);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Grab the newly created entry's credentials
dwRet = RasGetCredentials(NULL, lpszEntry, lpCred);
if(dwRet == ERROR_SUCCESS){
wprintf(L"The following credentials were retrieved for the entry: %s\n\tUser name: %s\n\tPassword: %s\n\tDomain: %s\n", lpszEntry, lpCred->szUserName, lpCred->szPassword, lpCred->szDomain);
}else{
wprintf(L"RasValidateEntryName failed: Error = %d\n", dwRet);
}
// Clean up: delete the new entry
dwRet = RasDeleteEntry(NULL, lpszEntry);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasDeleteEntry failed: Error = %d\n", dwRet);
}
HeapFree(GetProcessHeap(), 0, lpentry);
HeapFree(GetProcessHeap(), 0, lpCred);
return 0;
}
系统支持
客户端最小支持 | Windows 2000专业版 |
---|---|
服务端最小支持 | Windows 2000 Server |
Header | Ras.h |
Library | Rasapi32.lib |
DLL | Raspi32.dll |
Unicode和ANSI名称 | RasGetCredentialsW(Unicode)和RasGetCredentialsA(ANSI) |