RasGetCredentialsA 関数 (ras.h)

[アーティクル]
11/20/2024

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。

関数が失敗した場合、戻り値は次のいずれかのエラーコード、または Routing と Remote Access Error Codes または 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 は、Windows の今後のリリースではサポートされない可能性がある、RasGetEntryDialParams 関数よりも優先されます。

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 プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして RasGetCredentials を定義します。エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされる最小サーバー	Windows 2000 Server [デスクトップアプリのみ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	ras.h
ライブラリ	Rasapi32.lib
DLL	Rasapi32.dll

次の方法で共有

RasGetCredentialsA 関数 (ras.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース