RasGetCredentials

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)