RasGetCredentialsA 函式 (ras.h)

發行項
08/25/2023

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 中的值。

值	意義
ERROR_CANNOT_OPEN_PHONEBOOK	找不到指定的電話簿。
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	指定的專案不存在於電話簿中。
ERROR_INVALID_PARAMETER	lpCredentials參數為Null。
ERROR_INVALID_SIZE	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

另請參閱

RASCREDENTIALS

RasGetEntryDialParams

RasSetCredentials

遠端存取服務 (RAS) 概觀

遠端存取服務函式

RasGetCredentialsA 函式 (ras.h)

語法

參數

傳回值

備註

需求

另請參閱

意見反應

意見反應

其他資源