RasDialW

関数

RAS接続(ダイヤルアップ/VPN)を確立する(Unicode版)。

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

シグネチャ

// RASAPI32.dll  (Unicode / -W)
#include <windows.h>

DWORD RasDialW(
    RASDIALEXTENSIONS* param0,   // optional
    LPCWSTR param1,   // optional
    RASDIALPARAMSW* param2,
    DWORD param3,
    void* param4,   // optional
    HRASCONN* param5
);

パラメーター

名前	型	方向	説明
param0	RASDIALEXTENSIONS*	inoptional	ダイヤル拡張オプションを格納したRASDIALEXTENSIONS構造体へのポインタ。NULL可。
param1	LPCWSTR	inoptional	使用する電話帳ファイルのパスを指すワイド文字列。NULLで既定の電話帳を使う。
param2	RASDIALPARAMSW*	in	接続エントリ名や認証情報を格納したRASDIALPARAMSW構造体へのポインタ。
param3	DWORD	in	通知の種類を示す値。RASDIALFUNC等の解釈に影響する。
param4	void*	inoptional	進捗通知を受け取るウィンドウハンドルまたはコールバック関数へのポインタ。NULL可。
param5	HRASCONN*	out	確立されたRAS接続のハンドルを受け取るポインタ。

戻り値の型: DWORD

公式ドキュメント

RasDial 関数は、RAS クライアントと RAS サーバーの間に RAS 接続を確立します。接続データには、コールバックおよびユーザー認証の情報が含まれます。(Unicode)

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS であり、RAS 接続のハンドルが lphRasConn が指す変数に返されます。

関数が失敗した場合、戻り値は Routing and Remote Access Error Codes または Winerror.h に定義された値です。

解説(Remarks)

直ちに制御が返された後に発生するエラーは、 RasGetConnectStatus で検出できます。データは、アプリケーションが接続を切断するために RasHangUp を呼び出すまで利用できます。

*lphRasConn に NULL 以外の接続ハンドルが格納された場合、アプリケーションは最終的に RasHangUp を呼び出す必要があります。これは、 RasDial が 0 以外の値 (エラー) を返した場合にも当てはまります。

アプリケーションは、 RasDial の通知コールバック関数から RasHangUp を安全に呼び出すことができます。ただしその場合、切断はそのルーチンが復帰するまで実行されません。

lpRasDialExtensions が指す構造体で RDEOPT_PausedStates が有効になっている場合、 RasDial 関数は RASCS_PAUSED ビットが 1 に設定された状態に入るたびに一時停止します。そのような一時停止状態から RasDial を再開するには、最初の RasDial の呼び出しで *lphRasConn に返された接続ハンドルを渡して、 RasDial をもう一度呼び出します。一時停止状態から再開する際には、最初の RasDial の呼び出しで使用したものと同じ通知先を使用する必要があります。

lpvNotifier パラメーターは、進行状況の通知メッセージを受け取るウィンドウのハンドルです。進行状況の通知メッセージでは、wParam は RasDialFunc および RasDialFunc1 の rasconnstate パラメーターに相当し、lParam は RasDialFunc および RasDialFunc1 の dwError パラメーターに相当します。

進行状況の通知メッセージは、システムに登録されたメッセージコードを使用します。このメッセージコードの値は、次のようにして取得できます。

UINT unMsg = RegisterWindowMessageA( RASDIALEVENT );
if (unMsg == 0)
    unMsg = WM_RASDIALEVENT;

RAS は参照カウント付きの接続をサポートしています。ダイヤルするエントリが既に接続されている場合、 RasDial は SUCCESS を返し、その接続が参照されます。接続を切断するには、その接続に対する各 RasDial の呼び出しを RasHangUp の呼び出しと対にする必要があります。

一部の電話帳エントリは認証に拡張認証プロトコル (EAP) を必要とするため、呼び出し元は RasDial を呼び出す前に RasGetEapUserIdentity を呼び出す必要があります。 RasGetEapUserIdentity が ERROR_INVALID_FUNCTION_FOR_ENTRY を返した場合、その電話帳エントリは EAP を必要としません。ただし、 RasGetEapUserIdentity が NO_ERROR を返した場合、呼び出し元は RasGetEapUserIdentity から得た EAP の ID 情報を RASDIALEXTENSIONS の RasEapInfo メンバーと、 RASDIALPARAMS の szUserName メンバーにコピーする必要があります。詳細については RasGetEapUserIdentity を参照してください。電話帳エントリが EAP を必要とする場合、そのエントリの RASENTRY 構造体の dwfOptions メンバーに RASEO_RequireEAP フラグが含まれます。

RasDial が RASCS_CallbackSetByCaller 状態に入るように指定するには、最初の RasDial の呼び出しで lpRasDialParams->szCallbackNumber に "*" を設定します。この状態で通知ハンドラーが呼び出されたら、ユーザーから指定された番号をコールバック番号として設定します。

メモ

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

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

各言語での呼び出し定義

// RASAPI32.dll  (Unicode / -W)
#include <windows.h>

DWORD RasDialW(
    RASDIALEXTENSIONS* param0,   // optional
    LPCWSTR param1,   // optional
    RASDIALPARAMSW* param2,
    DWORD param3,
    void* param4,   // optional
    HRASCONN* param5
);

[DllImport("RASAPI32.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern uint RasDialW(
    IntPtr param0,   // RASDIALEXTENSIONS* optional
    [MarshalAs(UnmanagedType.LPWStr)] string param1,   // LPCWSTR optional
    IntPtr param2,   // RASDIALPARAMSW*
    uint param3,   // DWORD
    IntPtr param4,   // void* optional
    IntPtr param5   // HRASCONN* out
);

<DllImport("RASAPI32.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function RasDialW(
    param0 As IntPtr,   ' RASDIALEXTENSIONS* optional
    <MarshalAs(UnmanagedType.LPWStr)> param1 As String,   ' LPCWSTR optional
    param2 As IntPtr,   ' RASDIALPARAMSW*
    param3 As UInteger,   ' DWORD
    param4 As IntPtr,   ' void* optional
    param5 As IntPtr   ' HRASCONN* out
) As UInteger
End Function

' param0 : RASDIALEXTENSIONS* optional
' param1 : LPCWSTR optional
' param2 : RASDIALPARAMSW*
' param3 : DWORD
' param4 : void* optional
' param5 : HRASCONN* out
Declare PtrSafe Function RasDialW Lib "rasapi32" ( _
    ByVal param0 As LongPtr, _
    ByVal param1 As LongPtr, _
    ByVal param2 As LongPtr, _
    ByVal param3 As Long, _
    ByVal param4 As LongPtr, _
    ByVal param5 As LongPtr) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

RasDialW = ctypes.windll.rasapi32.RasDialW
RasDialW.restype = wintypes.DWORD
RasDialW.argtypes = [
    ctypes.c_void_p,  # param0 : RASDIALEXTENSIONS* optional
    wintypes.LPCWSTR,  # param1 : LPCWSTR optional
    ctypes.c_void_p,  # param2 : RASDIALPARAMSW*
    wintypes.DWORD,  # param3 : DWORD
    ctypes.POINTER(None),  # param4 : void* optional
    ctypes.c_void_p,  # param5 : HRASCONN* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('RASAPI32.dll')
RasDialW = Fiddle::Function.new(
  lib['RasDialW'],
  [
    Fiddle::TYPE_VOIDP,  # param0 : RASDIALEXTENSIONS* optional
    Fiddle::TYPE_VOIDP,  # param1 : LPCWSTR optional
    Fiddle::TYPE_VOIDP,  # param2 : RASDIALPARAMSW*
    -Fiddle::TYPE_INT,  # param3 : DWORD
    Fiddle::TYPE_VOIDP,  # param4 : void* optional
    Fiddle::TYPE_VOIDP,  # param5 : HRASCONN* out
  ],
  -Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "rasapi32")]
extern "system" {
    fn RasDialW(
        param0: *mut RASDIALEXTENSIONS,  // RASDIALEXTENSIONS* optional
        param1: *const u16,  // LPCWSTR optional
        param2: *mut RASDIALPARAMSW,  // RASDIALPARAMSW*
        param3: u32,  // DWORD
        param4: *mut (),  // void* optional
        param5: *mut *mut core::ffi::c_void  // HRASCONN* out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("RASAPI32.dll", CharSet = CharSet.Unicode)]
public static extern uint RasDialW(IntPtr param0, [MarshalAs(UnmanagedType.LPWStr)] string param1, IntPtr param2, uint param3, IntPtr param4, IntPtr param5);
"@
$api = Add-Type -MemberDefinition $sig -Name 'RASAPI32_RasDialW' -Namespace Win32 -PassThru
# $api::RasDialW(param0, param1, param2, param3, param4, param5)

#uselib "RASAPI32.dll"
#func global RasDialW "RasDialW" wptr, wptr, wptr, wptr, wptr, wptr
; RasDialW varptr(param0), param1, varptr(param2), param3, param4, param5   ; 戻り値は stat
; param0 : RASDIALEXTENSIONS* optional -> "wptr"
; param1 : LPCWSTR optional -> "wptr"
; param2 : RASDIALPARAMSW* -> "wptr"
; param3 : DWORD -> "wptr"
; param4 : void* optional -> "wptr"
; param5 : HRASCONN* out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "RASAPI32.dll"
#cfunc global RasDialW "RasDialW" var, wstr, var, int, sptr, sptr
; res = RasDialW(param0, param1, param2, param3, param4, param5)
; param0 : RASDIALEXTENSIONS* optional -> "var"
; param1 : LPCWSTR optional -> "wstr"
; param2 : RASDIALPARAMSW* -> "var"
; param3 : DWORD -> "int"
; param4 : void* optional -> "sptr"
; param5 : HRASCONN* out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "RASAPI32.dll"
#cfunc global RasDialW "RasDialW" sptr, wstr, sptr, int, sptr, sptr
; res = RasDialW(varptr(param0), param1, varptr(param2), param3, param4, param5)
; param0 : RASDIALEXTENSIONS* optional -> "sptr"
; param1 : LPCWSTR optional -> "wstr"
; param2 : RASDIALPARAMSW* -> "sptr"
; param3 : DWORD -> "int"
; param4 : void* optional -> "sptr"
; param5 : HRASCONN* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。