RasEnumEntriesA 関数 (ras.h)

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

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) の概要

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

次の方法で共有

RasEnumEntriesA 関数 (ras.h)

構文

パラメーター

戻り値

注釈

要件

こちらもご覧ください

フィードバック

その他のリソース