RasEnumEntriesA 関数 (ras.h)

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

RasEnumEntries 関数は、リモートアクセス電話帳内のすべてのエントリ名を一覧表示します。

構文

DWORD RasEnumEntriesA(
  [in]      LPCSTR          unnamedParam1,
  [in]      LPCSTR          unnamedParam2,
  [in, out] LPRASENTRYNAMEA unnamedParam3,
  [in, out] LPDWORD         unnamedParam4,
  [out]     LPDWORD         unnamedParam5
);

パラメーター

[in] unnamedParam1

引っ込み思案;は NULLする必要があります。

[in] unnamedParam2

電話帳 (PBK) ファイルの完全なパスとファイル名を指定する null で終わる文字列へのポインター。このパラメーターが NULL場合、関数は現在の既定の電話帳ファイルを使用します。既定の電話帳ファイルは、ダイヤルアップネットワーク] ダイアログボックスの [ユーザー設定 プロパティシートでユーザーが選択したものです。

このパラメーターが NULL場合、エントリは AllUsers プロファイルとユーザーのプロファイル内のすべてのリモートアクセス電話帳ファイルから列挙されます。

[in, out] unnamedParam3

出力時に、電話帳エントリごとに 1 つずつ、RASENTRYNAME 構造体の配列を受け取るバッファーへのポインター。

入力時に、アプリケーションは、渡される構造体のバージョンを識別するために、バッファー内の最初の RASENTRYNAME 構造体の dwSize メンバーを sizeof(RASENTRYNAME) に設定する必要があります。

[in, out] unnamedParam4

入力時に、lprasentrynameで指定されたバッファーのサイズ (バイト単位) 含む変数へのポインター。

出力時に、電話帳エントリに必要な RASENTRYNAME 構造体の配列のサイズをバイト単位で格納する変数へのポインター。

Windows Vista 以降: 必要なバッファーサイズを決定するには、lprasentryname NULLに設定 RasEnumEntries 呼び出します。 lpcb 指す変数を 0 に設定する必要があります。この関数は、lpcb 必要なバッファーサイズと ERROR_BUFFER_TOO_SMALLのエラーコードを返します。

[out] unnamedParam5

lprasentrynameで指定されたバッファーに書き込まれた電話帳エントリの数受け取る変数へのポインター。

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS。

関数が失敗した場合、戻り値は次のいずれかのエラーコード、または Routing と Remote Access Error Codes または Winerror.h からの値です。

価値	意味
ERROR_BUFFER_TOO_SMALL	lprasentryname バッファーのサイズが十分ではありません。 lpcb パラメーターは、関数を呼び出す前に設定する必要がある、lprasentryname パラメーターの dwSize メンバーより小さいです。この関数は、lpcbが指す変数で必要なバッファーサイズを返します。 Windows Vista 以降: lprasentryname バッファーは NULL に設定でき、lpcb が指す変数 0 に設定できます。この関数は、lpcbが指す変数に必要なバッファーサイズを返します。
ERROR_INVALID_SIZE	lprasentryname が指す RASENTRYNAME 構造体の dwSize の値は、現在のプラットフォームでサポートされていない構造体のバージョンを指定します。たとえば、Windows 95 では、RasEnumEntries は、dwSize が、rasENTRYNAME に dwFlags と szPhonebookPath メンバーが含まれていることを示している場合、このエラーを返します。これらのメンバーは Windows 95 でサポートされていないためです (Windows 2000 以降でのみサポートされます)。
ERROR_NOT_ENOUGH_MEMORY	この関数は、操作を完了するのに十分なメモリを割り当てませんでした。

備考

次のサンプルコードでは、Windows Vista 以降のバージョンの Windows 上の RAS 電話帳エントリを列挙します。このコードは、最初 RasEnumEntries を呼び出して、渡すバッファーのサイズを取得します。その後、RasEnumEntries を再度呼び出して、エントリを列挙します。 2 番目の呼び出しでは、バッファー内の最初の RASENTRYNAME 構造体の dwSize メンバーを sizeof(RASENTRYNAME) に設定して、構造体のバージョンを指定します。

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "raserror.h"
#pragma comment(lib, "rasapi32.lib")

DWORD __cdecl wmain(){

    DWORD dwCb = 0;
    DWORD dwRet = ERROR_SUCCESS;
    DWORD dwEntries = 0;
    LPRASENTRYNAME lpRasEntryName = NULL;
    
    // Call RasEnumEntries with lpRasEntryName = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS entry names.
        lpRasEntryName = (LPRASENTRYNAME) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasEntryName == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASENTRYNAME structure in the array must contain the structure size
        lpRasEntryName[0].dwSize = sizeof(RASENTRYNAME);
        
        // Call RasEnumEntries to enumerate all RAS entry names
        dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

        // If successful, print the RAS entry names 
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS entry names were found:\n");
            for (DWORD i = 0; i < dwEntries; i++){
                wprintf(L"%s\n", lpRasEntryName[i].szEntryName);
            }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasEntryName);
        lpRasEntryName = NULL;
        return 0;
    }

    // There was either a problem with RAS or there are RAS entry names to enumerate    
    if(dwEntries >= 1){
        wprintf(L"The operation failed to acquire the buffer size.\n");
    }else{
        wprintf(L"There were no RAS entry names found:.\n");
    }

    return 0;
}

手記

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

必要条件

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

次の方法で共有

RasEnumEntriesA 関数 (ras.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース