RasGetCredentialsA 函式 (ras.h)
RasGetCredentials 函式會擷取與指定 RAS 電話簿專案相關聯的使用者認證。
語法
DWORD RasGetCredentialsA(
[in] LPCSTR unnamedParam1,
[in] LPCSTR unnamedParam2,
[in, out] LPRASCREDENTIALSA unnamedParam3
);
參數
[in] unnamedParam1
Null終止字串的指標,指定電話簿 (PBK) 檔案的完整路徑和檔案名。 如果此參數為 Null,函式會使用目前的預設電話簿檔案。 預設電話簿檔案是由 [撥號網路] 對話方塊的 [ 使用者喜好設定 ] 屬性工作表中的使用者所選取的 檔案 。
[in] unnamedParam2
指定電話簿專案名稱之 Null終止字串的指標。
[in, out] unnamedParam3
在輸出時, RASCREDENTIALS 結構的指標會接收與指定電話簿專案相關聯的使用者認證。
在輸入時,將 結構的 dwSize 成員設定為 sizeof (RASCREDENTIALS) ,並設定 dwMask 成員以指出要擷取的認證資訊。 當函式傳回時, dwMask 會指出已成功擷取的成員。
傳回值
如果函式成功,傳回值 會ERROR_SUCCESS。
如果函式失敗,傳回值是下列其中一個錯誤碼,或是 路由和遠端存取錯誤碼 或 Winerror.h 中的值。
值 | 意義 |
---|---|
|
找不到指定的電話簿。 |
|
指定的專案不存在於電話簿中。 |
|
lpCredentials參數為Null。 |
|
RASCREDENTIALS結構的dwSize成員是無法辨識的值。 |
備註
RasGetCredentials函式會擷取最後一位使用者的認證,以便使用指定的電話簿專案進行連線,或後續在電話簿專案的RasSetCredentials函式呼叫中指定的認證。
此函式是安全地擷取與 RAS 電話簿專案相關聯之認證的慣用方式。 RasGetCredentials 取代 RasGetEntryDialParams 函式,未來 Windows 版本可能不支援此功能。
RasGetCredentials 不會傳回實際的密碼。 相反地,RASCREDENTIALS結構的szPassword成員包含已儲存密碼的控制碼。 在 後續對 RasSetCredentials 和 RasDial的呼叫中,將這個控制碼取代為已儲存的密碼。 當出現此控制碼時, RasDial 會擷取並使用儲存的密碼。 此控制碼的值可能會在未來的作業系統版本中變更;請勿開發取決於此值內容或格式的程式碼。
如果系統已為指定的專案儲存密碼,RASCREDENTIALS的dwMask成員就會包含RASCM_Password旗標。 如果系統未儲存此專案的密碼, 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 initialization 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 initialization 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;
}
注意
ras.h 標頭會根據 UNICODE 預處理器常數的定義,將 RasGetCredentials 定義為別名,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼,可能會導致編譯或執行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
需求
最低支援的用戶端 | Windows 2000 專業版 [僅限傳統型應用程式] |
最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
目標平台 | Windows |
標頭 | ras.h |
程式庫 | Rasapi32.lib |
Dll | Rasapi32.dll |