RasEnumEntriesA 関数 (ras.h)

  • [アーティクル]

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 の場合、関数は現在の既定の phone-book ファイルを使用します。 既定の電話帳ファイルは、[ダイヤルアップ ネットワーク] ダイアログ ボックスの [ユーザー設定] プロパティ シートでユーザーが選択したファイルです。

このパラメーターが 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。

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

要件

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

こちらもご覧ください

RASENTRYNAME

RasEnumConnections

リモート アクセス サービス (RAS) の概要

リモート アクセス サービス関数