RasGetCredentialsA 関数 (ras.h)

[アーティクル]
08/25/2023

RasGetCredentials 関数は、指定された RAS 電話帳エントリに関連付けられているユーザー資格情報を取得します。

構文

DWORD RasGetCredentialsA(
  [in]      LPCSTR            unnamedParam1,
  [in]      LPCSTR            unnamedParam2,
  [in, out] LPRASCREDENTIALSA unnamedParam3
);

パラメーター

[in] unnamedParam1

電話帳 (PBK) ファイルの完全なパスとファイル名を指定する null で終わる文字列へのポインター。このパラメーターが 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 ヘッダーは RasGetCredentials をエイリアスとして定義します。このエイリアスは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイルエラーまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件


サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	ras.h
Library	Rasapi32.lib
[DLL]	Rasapi32.dll

RasGetCredentialsA 関数 (ras.h)

構文

パラメーター

戻り値

解説

要件

関連項目

フィードバック

フィードバック

その他のリソース