ホーム › NetworkManagement.Rras › RasEntryDlgW

RasEntryDlgW

関数

RAS電話帳エントリの作成・編集ダイアログを表示する(Unicode版)。

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

シグネチャ

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

BOOL RasEntryDlgW(
    LPWSTR lpszPhonebook,   // optional
    LPWSTR lpszEntry,   // optional
    RASENTRYDLGW* lpInfo
);

パラメーター

名前	型	方向	説明
lpszPhonebook	LPWSTR	inoptional	電話帳 (PBK) ファイルのフルパスとファイル名を指定する null 終端文字列へのポインターです。このパラメーターが NULL の場合、関数は現在の既定の電話帳ファイルを使用します。既定の電話帳ファイルは、ダイヤルアップネットワークダイアログボックスのユーザー設定プロパティシートでユーザーが選択したファイルです。
lpszEntry	LPWSTR	inoptional	編集、コピー、または作成する電話帳エントリの名前を指定する null 終端文字列へのポインターです。エントリを編集またはコピーする場合、このパラメーターは既存の電話帳エントリの名前です。エントリをコピーする場合は、 RASENTRYDLG 構造体の dwFlags メンバーに RASEDFLAG_CloneEntry フラグを設定します。メモ RASEDFLAG_CloneEntry フラグは、 Windows Vista および Windows Server 2008 以降では非推奨です。以降のバージョンでは変更されるか、使用できなくなる可能性があります。代わりに、RasGetEntryProperties を呼び出してエントリを取得し、続いて RasSetEntryProperties を呼び出して新しい名前でエントリを保存することで、エントリをコピーしてください。エントリを作成する場合、このパラメーターはユーザーが変更できる既定の新しいエントリ名です。このパラメーターが NULL の場合、関数が既定の名前を提供します。エントリを作成する場合は、 RASENTRYDLG 構造体の dwFlags メンバーに RASEDFLAG_NewEntry フラグを設定します。
lpInfo	RASENTRYDLGW*	inout	追加の入力パラメーターおよび出力パラメーターを指定する RASENTRYDLG 構造体へのポインターです。この構造体の dwSize メンバーには sizeof(RASENTRYDLG) を指定する必要があります。エントリを作成するのか、編集するのか、コピーするのかを示すには dwFlags メンバーを使用します。エラーが発生した場合、dwError メンバーにエラーコードが返されます。それ以外の場合は 0 が返されます。

名前

型

方向

説明

lpszPhonebook

LPWSTR

inoptional

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

lpszEntry

LPWSTR

inoptional

編集、コピー、または作成する電話帳エントリの名前を指定する null 終端文字列へのポインターです。

エントリを編集またはコピーする場合、このパラメーターは既存の電話帳エントリの名前です。エントリをコピーする場合は、 RASENTRYDLG 構造体の dwFlags メンバーに RASEDFLAG_CloneEntry フラグを設定します。

メモ RASEDFLAG_CloneEntry フラグは、 Windows Vista および Windows Server 2008 以降では非推奨です。以降のバージョンでは変更されるか、使用できなくなる可能性があります。代わりに、RasGetEntryProperties を呼び出してエントリを取得し、続いて RasSetEntryProperties を呼び出して新しい名前でエントリを保存することで、エントリをコピーしてください。

エントリを作成する場合、このパラメーターはユーザーが変更できる既定の新しいエントリ名です。このパラメーターが NULL の場合、関数が既定の名前を提供します。エントリを作成する場合は、 RASENTRYDLG 構造体の dwFlags メンバーに RASEDFLAG_NewEntry フラグを設定します。

lpInfo

RASENTRYDLGW*

inout

追加の入力パラメーターおよび出力パラメーターを指定する RASENTRYDLG 構造体へのポインターです。この構造体の dwSize メンバーには sizeof(RASENTRYDLG) を指定する必要があります。エントリを作成するのか、編集するのか、コピーするのかを示すには dwFlags メンバーを使用します。エラーが発生した場合、dwError メンバーにエラーコードが返されます。それ以外の場合は 0 が返されます。

戻り値の型: BOOL

公式ドキュメント

RasEntryDlg 関数は、ユーザーが電話帳エントリを操作できるモーダルなプロパティシートを表示します。(Unicode)

戻り値

ユーザーが電話帳エントリを作成、コピー、または編集した場合、戻り値は TRUE です。それ以外の場合、関数は FALSE を返します。

エラーが発生した場合、RasEntryDlg は RASENTRYDLG 構造体の dwError メンバーに、Routing and Remote Access Error Codes または Winerror.h の値を設定します。

解説(Remarks)

RasCreatePhonebookEntry 関数および RasEditPhonebookEntry 関数は、 RasEntryDlg 関数を呼び出します。

次のサンプルコードは、新しいエントリを作成するためのプロパティシートを表示します。lpszEntry 変数は、新しいエントリの既定の名前を指定します。

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

DWORD __cdecl wmain(){

    DWORD dwRet = ERROR_SUCCESS;
    BOOL nRet = TRUE;
    LPTSTR lpszEntry = L"EntryName";

    // ヒープ メモリを割り当てて RASENTRYDLG 構造体を初期化する
    LPRASENTRYDLG lpEntry = (LPRASENTRYDLG)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRYDLG));
    if (lpEntry == NULL){
        wprintf(L"HeapAlloc failed.
");
        return 0;
    }
    
    // RASENTRYDLG->dwSize メンバーを初期化しないと、以降の RRAS API は失敗する。
    lpEntry->dwSize = sizeof(RASENTRYDLG);
    lpEntry->dwFlags |= RASEDFLAG_NewEntry;

    // ユーザー ダイアログを使用して新しいエントリを作成する
    nRet = RasEntryDlg(NULL, lpszEntry, lpEntry);

    // エラー コードは lpEntry に返される
    dwRet = lpEntry->dwError;
    
    if (nRet == TRUE) {
        wprintf(L"New entry created: %s
", lpEntry->szEntry);

        // クリーンアップ: 新しいエントリを削除する
        dwRet = RasDeleteEntry(NULL, lpszEntry);
        if (dwRet != ERROR_SUCCESS) {
            wprintf(L"RasDeleteEntry failed: Error = %d
", dwRet);
        }

    } 
    else {
        if (dwRet != ERROR_SUCCESS) {
            wprintf(L"RasEntryDlg failed: Error = %d
", dwRet);
        }
        else {
            wprintf(L"User pressed Cancel
");
        }
    }

    HeapFree(GetProcessHeap(), 0, lpEntry);
    return 0;
}

メモ

rasdlg.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして RASENTRYDLG を定義しています。エンコードニュートラルなエイリアスの使用と、エンコードニュートラルでないコードを混在させると、不一致が生じ、コンパイルエラーや実行時エラーの原因となる可能性があります。詳細については、関数プロトタイプの規則を参照してください。

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

各言語での呼び出し定義

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

BOOL RasEntryDlgW(
    LPWSTR lpszPhonebook,   // optional
    LPWSTR lpszEntry,   // optional
    RASENTRYDLGW* lpInfo
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("RASDLG.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern bool RasEntryDlgW(
    [MarshalAs(UnmanagedType.LPWStr)] string lpszPhonebook,   // LPWSTR optional
    [MarshalAs(UnmanagedType.LPWStr)] string lpszEntry,   // LPWSTR optional
    IntPtr lpInfo   // RASENTRYDLGW* in/out
);

<DllImport("RASDLG.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function RasEntryDlgW(
    <MarshalAs(UnmanagedType.LPWStr)> lpszPhonebook As String,   ' LPWSTR optional
    <MarshalAs(UnmanagedType.LPWStr)> lpszEntry As String,   ' LPWSTR optional
    lpInfo As IntPtr   ' RASENTRYDLGW* in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' lpszPhonebook : LPWSTR optional
' lpszEntry : LPWSTR optional
' lpInfo : RASENTRYDLGW* in/out
Declare PtrSafe Function RasEntryDlgW Lib "rasdlg" ( _
    ByVal lpszPhonebook As LongPtr, _
    ByVal lpszEntry As LongPtr, _
    ByVal lpInfo 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

RasEntryDlgW = ctypes.windll.rasdlg.RasEntryDlgW
RasEntryDlgW.restype = wintypes.BOOL
RasEntryDlgW.argtypes = [
    wintypes.LPCWSTR,  # lpszPhonebook : LPWSTR optional
    wintypes.LPCWSTR,  # lpszEntry : LPWSTR optional
    ctypes.c_void_p,  # lpInfo : RASENTRYDLGW* in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('RASDLG.dll')
RasEntryDlgW = Fiddle::Function.new(
  lib['RasEntryDlgW'],
  [
    Fiddle::TYPE_VOIDP,  # lpszPhonebook : LPWSTR optional
    Fiddle::TYPE_VOIDP,  # lpszEntry : LPWSTR optional
    Fiddle::TYPE_VOIDP,  # lpInfo : RASENTRYDLGW* in/out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "rasdlg")]
extern "system" {
    fn RasEntryDlgW(
        lpszPhonebook: *mut u16,  // LPWSTR optional
        lpszEntry: *mut u16,  // LPWSTR optional
        lpInfo: *mut RASENTRYDLGW  // RASENTRYDLGW* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("RASDLG.dll", CharSet = CharSet.Unicode)]
public static extern bool RasEntryDlgW([MarshalAs(UnmanagedType.LPWStr)] string lpszPhonebook, [MarshalAs(UnmanagedType.LPWStr)] string lpszEntry, IntPtr lpInfo);
"@
$api = Add-Type -MemberDefinition $sig -Name 'RASDLG_RasEntryDlgW' -Namespace Win32 -PassThru
# $api::RasEntryDlgW(lpszPhonebook, lpszEntry, lpInfo)

#uselib "RASDLG.dll"
#func global RasEntryDlgW "RasEntryDlgW" wptr, wptr, wptr
; RasEntryDlgW lpszPhonebook, lpszEntry, varptr(lpInfo)   ; 戻り値は stat
; lpszPhonebook : LPWSTR optional -> "wptr"
; lpszEntry : LPWSTR optional -> "wptr"
; lpInfo : RASENTRYDLGW* in/out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "RASDLG.dll"
#cfunc global RasEntryDlgW "RasEntryDlgW" wstr, wstr, var
; res = RasEntryDlgW(lpszPhonebook, lpszEntry, lpInfo)
; lpszPhonebook : LPWSTR optional -> "wstr"
; lpszEntry : LPWSTR optional -> "wstr"
; lpInfo : RASENTRYDLGW* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "RASDLG.dll"
#cfunc global RasEntryDlgW "RasEntryDlgW" wstr, wstr, sptr
; res = RasEntryDlgW(lpszPhonebook, lpszEntry, varptr(lpInfo))
; lpszPhonebook : LPWSTR optional -> "wstr"
; lpszEntry : LPWSTR optional -> "wstr"
; lpInfo : RASENTRYDLGW* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。