ホーム › NetworkManagement.Rras › RasEnumAutodialAddressesA

RasEnumAutodialAddressesA

関数

自動ダイヤルに登録された全アドレスを列挙する(ANSI版)。

DLLRASAPI32.dll文字セットANSI (-A)呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// RASAPI32.dll  (ANSI / -A)
#include <windows.h>

DWORD RasEnumAutodialAddressesA(
    LPSTR* lppRasAutodialAddresses,   // optional
    DWORD* lpdwcbRasAutodialAddresses,
    DWORD* lpdwcRasAutodialAddresses
);

パラメーター

名前	型	方向	説明
lppRasAutodialAddresses	LPSTR*	inoutoptional	文字列ポインターの配列へのポインター。バッファーの末尾には、文字列自体を格納するための追加の領域が必要です。出力時、各文字列は AutoDial マッピングデータベース内のアドレス名を受け取ります。入力時に lppAddresses が NULL の場合、 RasEnumAutodialAddresses は lpdwcbAddresses および lpdwcAddresses パラメーターに、必要なサイズ (バイト単位) とデータベース内のアドレスエントリ数を設定します。
lpdwcbRasAutodialAddresses	DWORD*	inout	入力時に、lpRasEnumAutodialAddressespAddresses パラメーターで指定されたバッファーのサイズ (バイト単位) を格納する変数へのポインター。メモ必要なバッファーサイズを求めるには、lppAddresses に NULL を指定して RasEnumAutodialAddresses を呼び出します。lpdwcbAddresses が指す変数は 0 に設定してください。この関数は必要なバッファーサイズを lpdwcbAddresses に返し、エラーコード ERROR_BUFFER_TOO_SMALL を返します。
lpdwcRasAutodialAddresses	DWORD*	out	lppAddresses バッファーに返されたアドレス文字列の数を受け取る変数へのポインター。

名前

型

方向

説明

lppRasAutodialAddresses

LPSTR*

inoutoptional

文字列ポインターの配列へのポインター。バッファーの末尾には、文字列自体を格納するための追加の領域が必要です。

出力時、各文字列は AutoDial マッピングデータベース内のアドレス名を受け取ります。

入力時に lppAddresses が NULL の場合、 RasEnumAutodialAddresses は lpdwcbAddresses および lpdwcAddresses パラメーターに、必要なサイズ (バイト単位) とデータベース内のアドレスエントリ数を設定します。

lpdwcbRasAutodialAddresses

DWORD*

inout

入力時に、lpRasEnumAutodialAddressespAddresses パラメーターで指定されたバッファーのサイズ (バイト単位) を格納する変数へのポインター。

メモ

必要なバッファーサイズを求めるには、lppAddresses に NULL を指定して RasEnumAutodialAddresses を呼び出します。lpdwcbAddresses が指す変数は 0 に設定してください。この関数は必要なバッファーサイズを lpdwcbAddresses に返し、エラーコード ERROR_BUFFER_TOO_SMALL を返します。

lpdwcRasAutodialAddresses

DWORD*

out

lppAddresses バッファーに返されたアドレス文字列の数を受け取る変数へのポインター。

戻り値の型: DWORD

公式ドキュメント

RasEnumAutodialAddresses 関数は、AutoDial マッピングデータベース内のすべてのアドレスの一覧を返します。(ANSI)

戻り値

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

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

値	意味
ERROR_INVALID_PARAMETER	lpdwcbAddresses または lpdwcAddresses パラメーターに NULL が渡されました。
ERROR_BUFFER_TOO_SMALL	lppAddresses バッファーが NULL で、lpdwcbAddresses が 0 でした。この関数は、lpdwcbAddresses が指す変数に必要なバッファーサイズを返します。

解説(Remarks)

次のコード例では、RasEnumAutodialAddresses を使用して Autodial マッピングデータベースを列挙します。

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "raserror.h"
#include <tchar.h>

DWORD __cdecl wmain(){

    DWORD dwBytes = 0;
    DWORD dwRet = ERROR_SUCCESS;
    DWORD dwAddresses = 0;
    LPTSTR * lppAddresses = NULL;
    LPCTSTR lpEntryAddress = L"www.microsoft.com";

    // Allocate memory for a new Autodial address to add to the mapping database
    LPRASAUTODIALENTRY lpentry = (LPRASAUTODIALENTRY) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASAUTODIALENTRY));
    lpentry->dwSize = sizeof(RASAUTODIALENTRY);

    // Add a (non-functional) address to the Autodial mapping database
    // (this ensures RasEnumAutodialAddresses() has something to return)
    dwRet = RasSetAutodialAddress(lpEntryAddress, 0, lpentry, lpentry->dwSize, 1);
    
    // Call RasEnumAutodialAddresses() with lppAddresses = NULL. dwBytes is returned with the 
    // required buffer size and a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumAutodialAddresses(lppAddresses, &dwBytes, &dwAddresses);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS Autodial addresses.
        lppAddresses = (LPTSTR *) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwBytes);
        if (lppAddresses == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        
        // Call RasEnumAutodialAddresses() to enumerate all RAS Autodial addresses
        dwRet = RasEnumAutodialAddresses(lppAddresses, &dwBytes, &dwAddresses);

        // If successful, print the RAS Autodial addresses
        if (dwRet == ERROR_SUCCESS){
            wprintf(L"The following RAS Autodial addresses were found:\n");
            for (DWORD i = 0; i < dwAddresses; i++){
                wprintf(L"%s\n", lppAddresses[i]);
            }
        }
        // Remove the address
        dwRet = RasSetAutodialAddress(lpEntryAddress, 0, NULL, 0, 0);
        
        //Deallocate memory for the address buffers
        HeapFree(GetProcessHeap(), 0, lppAddresses);    
        HeapFree(GetProcessHeap(), 0, lpentry);
        lppAddresses = NULL;
        return 0;
    }

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

    // Remove the address
    dwRet = RasSetAutodialAddress(lpEntryAddress, 0, NULL, 0, 0);
    HeapFree(GetProcessHeap(), 0, lpentry);
    return 0;
}

メモ

ras.h ヘッダーは、UNICODE プリプロセッサー定数の定義に応じてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして RasEnumAutodialAddresses を定義しています。エンコーディング中立なエイリアスと、エンコーディング中立ではないコードを混在させると、不一致が生じてコンパイルエラーや実行時エラーの原因となることがあります。詳しくは、Conventions for Function Prototypes を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// RASAPI32.dll  (ANSI / -A)
#include <windows.h>

DWORD RasEnumAutodialAddressesA(
    LPSTR* lppRasAutodialAddresses,   // optional
    DWORD* lpdwcbRasAutodialAddresses,
    DWORD* lpdwcRasAutodialAddresses
);

[DllImport("RASAPI32.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern uint RasEnumAutodialAddressesA(
    IntPtr lppRasAutodialAddresses,   // LPSTR* optional, in/out
    ref uint lpdwcbRasAutodialAddresses,   // DWORD* in/out
    out uint lpdwcRasAutodialAddresses   // DWORD* out
);

<DllImport("RASAPI32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function RasEnumAutodialAddressesA(
    lppRasAutodialAddresses As IntPtr,   ' LPSTR* optional, in/out
    ByRef lpdwcbRasAutodialAddresses As UInteger,   ' DWORD* in/out
    <Out> ByRef lpdwcRasAutodialAddresses As UInteger   ' DWORD* out
) As UInteger
End Function

' lppRasAutodialAddresses : LPSTR* optional, in/out
' lpdwcbRasAutodialAddresses : DWORD* in/out
' lpdwcRasAutodialAddresses : DWORD* out
Declare PtrSafe Function RasEnumAutodialAddressesA Lib "rasapi32" ( _
    ByVal lppRasAutodialAddresses As LongPtr, _
    ByRef lpdwcbRasAutodialAddresses As Long, _
    ByRef lpdwcRasAutodialAddresses As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

RasEnumAutodialAddressesA = ctypes.windll.rasapi32.RasEnumAutodialAddressesA
RasEnumAutodialAddressesA.restype = wintypes.DWORD
RasEnumAutodialAddressesA.argtypes = [
    ctypes.c_void_p,  # lppRasAutodialAddresses : LPSTR* optional, in/out
    ctypes.POINTER(wintypes.DWORD),  # lpdwcbRasAutodialAddresses : DWORD* in/out
    ctypes.POINTER(wintypes.DWORD),  # lpdwcRasAutodialAddresses : DWORD* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('RASAPI32.dll')
RasEnumAutodialAddressesA = Fiddle::Function.new(
  lib['RasEnumAutodialAddressesA'],
  [
    Fiddle::TYPE_VOIDP,  # lppRasAutodialAddresses : LPSTR* optional, in/out
    Fiddle::TYPE_VOIDP,  # lpdwcbRasAutodialAddresses : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # lpdwcRasAutodialAddresses : DWORD* out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "rasapi32")]
extern "system" {
    fn RasEnumAutodialAddressesA(
        lppRasAutodialAddresses: *mut *mut u8,  // LPSTR* optional, in/out
        lpdwcbRasAutodialAddresses: *mut u32,  // DWORD* in/out
        lpdwcRasAutodialAddresses: *mut u32  // DWORD* out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("RASAPI32.dll", CharSet = CharSet.Ansi)]
public static extern uint RasEnumAutodialAddressesA(IntPtr lppRasAutodialAddresses, ref uint lpdwcbRasAutodialAddresses, out uint lpdwcRasAutodialAddresses);
"@
$api = Add-Type -MemberDefinition $sig -Name 'RASAPI32_RasEnumAutodialAddressesA' -Namespace Win32 -PassThru
# $api::RasEnumAutodialAddressesA(lppRasAutodialAddresses, lpdwcbRasAutodialAddresses, lpdwcRasAutodialAddresses)

#uselib "RASAPI32.dll"
#func global RasEnumAutodialAddressesA "RasEnumAutodialAddressesA" sptr, sptr, sptr
; RasEnumAutodialAddressesA varptr(lppRasAutodialAddresses), varptr(lpdwcbRasAutodialAddresses), varptr(lpdwcRasAutodialAddresses)   ; 戻り値は stat
; lppRasAutodialAddresses : LPSTR* optional, in/out -> "sptr"
; lpdwcbRasAutodialAddresses : DWORD* in/out -> "sptr"
; lpdwcRasAutodialAddresses : DWORD* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "RASAPI32.dll"
#cfunc global RasEnumAutodialAddressesA "RasEnumAutodialAddressesA" var, var, var
; res = RasEnumAutodialAddressesA(lppRasAutodialAddresses, lpdwcbRasAutodialAddresses, lpdwcRasAutodialAddresses)
; lppRasAutodialAddresses : LPSTR* optional, in/out -> "var"
; lpdwcbRasAutodialAddresses : DWORD* in/out -> "var"
; lpdwcRasAutodialAddresses : DWORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "RASAPI32.dll"
#cfunc global RasEnumAutodialAddressesA "RasEnumAutodialAddressesA" sptr, sptr, sptr
; res = RasEnumAutodialAddressesA(varptr(lppRasAutodialAddresses), varptr(lpdwcbRasAutodialAddresses), varptr(lpdwcRasAutodialAddresses))
; lppRasAutodialAddresses : LPSTR* optional, in/out -> "sptr"
; lpdwcbRasAutodialAddresses : DWORD* in/out -> "sptr"
; lpdwcRasAutodialAddresses : DWORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。