phoneInitializeExW

関数

拡張パラメータ付きで電話TAPIを初期化する関数のUnicode版。

DLLTAPI32.dll文字セットUnicode (-W)呼出規約winapi

シグネチャ

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

INT phoneInitializeExW(
    DWORD* lphPhoneApp,
    HINSTANCE hInstance,
    PHONECALLBACK lpfnCallback,
    LPCWSTR lpszFriendlyAppName,
    DWORD* lpdwNumDevs,
    DWORD* lpdwAPIVersion,
    PHONEINITIALIZEEXPARAMS* lpPhoneInitializeExParams
);

パラメーター

名前	型	方向	説明
lphPhoneApp	DWORD*	inout	TAPI に対するアプリケーションの使用ハンドルが格納される場所へのポインター。
hInstance	HINSTANCE	in	クライアントアプリケーションまたは DLL のインスタンスハンドル。アプリケーションまたは DLL はこのパラメーターに NULL を渡すことができ、その場合 TAPI はプロセスのルート実行可能ファイルのモジュールハンドルを使用します。
lpfnCallback	PHONECALLBACK	in	アプリケーションがイベント通知に「隠しウィンドウ(hidden window)」方式を使用する場合に、回線デバイス、アドレス、または呼び出しの状態やイベントを判別するために呼び出されるコールバック関数のアドレス(詳細については phoneCallbackFunc を参照してください)。アプリケーションが「イベントハンドル(event handle)」または「完了ポート(completion port)」のイベント通知メカニズムを選択する場合、このパラメーターは無視され、NULL を設定する必要があります。
lpszFriendlyAppName	LPCWSTR	in	表示可能な文字のみを含む null 終端文字列へのポインター。このパラメーターが NULL でない場合、アプリケーションが提供するアプリケーション名を格納します。この名前は PHONESTATUS 構造体で提供され、どのアプリケーションが電話機デバイスの所有権を持っているかをユーザーにわかりやすい形で示します。lpszFriendlyAppName が NULL の場合は、代わりにアプリケーションのモジュールファイル名( GetModuleFileName 関数が返す値)が使用されます。
lpdwNumDevs	DWORD*	inout	DWORD へのポインター。この要求が正常に完了すると、この場所にはアプリケーションが利用できる電話機デバイスの数が格納されます。
lpdwAPIVersion	DWORD*	inout	DWORD へのポインター。アプリケーションは、この関数を呼び出す前に、サポートするよう設計されている最も高い API バージョンをこの DWORD に設定する必要があります(たとえば、 phoneNegotiateAPIVersion の dwAPIHighVersion パラメーターに渡すのと同じ値)。実際より高い値を使用してはならず、値は正確に設定する必要があります。TAPI は、より新しいメッセージや構造体を、アプリケーションのバージョンがサポートする値や形式に変換します。この要求が正常に完了すると、この場所には TAPI がサポートする最も高い API バージョンが格納されます。これにより、アプリケーションは古いバージョンの TAPI が入ったシステムにインストールされていることを検出し、それに適応できます。
lpPhoneInitializeExParams	PHONEINITIALIZEEXPARAMS*	inout	アプリケーションと TAPI の関連付けを確立するために使用される追加のパラメーター(具体的には、アプリケーションが選択したイベント通知メカニズムとそれに関連するパラメーター)を含む、 PHONEINITIALIZEEXPARAMS 型の構造体へのポインター。

戻り値の型: INT

公式ドキュメント

phoneInitializeEx 関数は、アプリケーションが電話機(phone)抽象化を以降利用するために、TAPI の使用を初期化します。(Unicode)

戻り値

要求が成功した場合は 0 を、エラーが発生した場合は負のエラー番号を返します。返される可能性のある値は次のとおりです。

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

解説(Remarks)

アプリケーションは、TAPI がテレフォニーイベントをアプリケーションに通知するメカニズムとして、Hidden Window、Event Handle、Completion Port の 3 つのうちいずれか 1 つを選択する必要があります。

Hidden Window メカニズムは、 PHONEINITIALIZEEXPARAMS 構造体の dwOptions メンバーに PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW を指定することで選択します。このメカニズム(TAPI バージョン 1.x のアプリケーションで利用できる唯一のメカニズム)では、TAPI は phoneInitializeEx 関数の実行中にアプリケーションのコンテキストでウィンドウを作成し、そのウィンドウをサブクラス化して、そこにポストされるすべてのメッセージが TAPI 自身の WNDPROC で処理されるようにします。TAPI はアプリケーションに配信するメッセージがあると、隠しウィンドウにメッセージをポストします。メッセージが受け取られると(これはアプリケーションが Windows の GetMessage 関数を呼び出したときにのみ発生します)、Windows はプロセスのコンテキストをそのアプリケーションのものに切り替え、TAPI 内の WNDPROC を呼び出します。その後 TAPI は、アプリケーションが phoneInitializeEx(TAPI バージョン 1.3 および 1.4 のアプリケーションの場合は phoneInitialize)の呼び出し時にパラメーターとして渡したポインターが指す phoneCallbackFunc を呼び出して、メッセージをアプリケーションに配信します。このメカニズムでは、アプリケーションがメッセージキューを持つ必要があり(これはサービスプロセスにとっては望ましくありません)、テレフォニーイベントの処理が遅延しないようにそのキューを定期的に処理する必要があります。隠しウィンドウは、 phoneShutdown 関数の実行中に TAPI によって破棄されます。
Event Handle メカニズムは、 PHONEINITIALIZEEXPARAMS 構造体の dwOptions メンバーに PHONEINITIALIZEEXOPTION_USEEVENT を指定することで選択します。このメカニズムでは、TAPI はアプリケーションに代わってイベントオブジェクトを作成し、そのオブジェクトへのハンドルを PHONEINITIALIZEEXPARAMS の hEvent メンバーで返します。アプリケーションはこのイベントをいかなる方法でも操作してはなりません(たとえば、 SetEvent、 ResetEvent、 CloseHandle などを呼び出してはなりません)。そうしないと動作は未定義になります。アプリケーションは、 WaitForSingleObject や MsgWaitForMultipleObjects などの関数でこのイベントを待機することのみができます。TAPI は、アプリケーション向けのテレフォニーイベント通知が保留中になるたびにこのイベントをシグナル状態にします。アプリケーションは phoneGetMessage を呼び出してメッセージの内容を取得する必要があります。保留中のイベントがなくなると、TAPI はイベントをリセットします。イベントハンドルは、 phoneShutdown 関数の実行中に TAPI によってクローズされ、イベントオブジェクトも破棄されます。アプリケーションは、作成されたイベントハンドルを待機する必要はありません。代わりに phoneGetMessage を呼び出し、メッセージがキューに入るまでブロックさせることもできます。
Completion Port メカニズムは、 PHONEINITIALIZEEXPARAMS 構造体の dwOptions メンバーに PHONEINITIALIZEEXOPTION_USECOMPLETION PORT を指定することで選択します。このメカニズムでは、テレフォニーイベントをアプリケーションに送信する必要が生じるたびに、TAPI は PostQueuedCompletionStatus を使用して、アプリケーションが PHONEINITIALIZEEXPARAMS の hCompletionPort メンバーで指定した完了ポートに、アプリケーションが PHONEINITIALIZEEXPARAMS の dwCompletionKey メンバーで指定した完了キーを付けてイベントを送信します。アプリケーションは、事前に CreateIoCompletionPort を使用して完了ポートを作成しておく必要があります。アプリケーションは GetQueuedCompletionStatus を使用してイベントを取得します。GetQueuedCompletionStatus から戻ると、アプリケーションには、指定した dwCompletionKey が lpCompletionKey パラメーターの指す DWORD に書き込まれ、 PHONEMESSAGE 構造体へのポインターが lpOverlapped の指す場所に返されます。アプリケーションはイベントを処理した後、 LocalFree を呼び出して、 PHONEMESSAGE 構造体を格納するために使用されていたメモリーを解放する必要があります。完了ポートはアプリケーションが作成したものであるため(その結果、他の目的にも共有できます)、アプリケーションがそれをクローズする必要があります。ただし、 phoneShutdown を呼び出すまでは完了ポートをクローズしてはなりません。

マルチスレッドのアプリケーションが Event Handle メカニズムを使用して複数のスレッドがそのハンドルを待機している場合、または Completion Port 通知メカニズムを使用して複数のスレッドがそのポートを待機している場合、テレフォニーイベントが順序どおりに処理されない可能性があります。これは TAPI からのイベント配信の順序によるものではなく、スレッドのタイムスライスや、別々のプロセッサー上でスレッドが実行されることに起因します。

PHONEERR_REINIT が返され、TAPI の再初期化が要求されている場合(たとえば、テレフォニーサービスプロバイダーの追加または削除の結果)、 phoneInitializeEx の要求は、最後のアプリケーションが( phoneShutdown を使用して)API の使用を終了するまで、このエラーで拒否されます。その時点で新しい構成が有効になり、アプリケーションは再び phoneInitializeEx を呼び出せるようになります。

PHONEERR_INVALPARAM エラー値が返された場合は、指定された hInstance パラメーターが無効です。

アプリケーションは、ゼロから dwNumDevs マイナス 1 までの範囲の電話機デバイス識別子を使用して、個々の電話機デバイスを参照できます。アプリケーションは、 phoneGetDevCaps でデバイス機能を照会せずに、これらの電話機デバイスが特定の TAPI 機能を備えていると想定してはなりません。

メモ

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

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

各言語での呼び出し定義

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

INT phoneInitializeExW(
    DWORD* lphPhoneApp,
    HINSTANCE hInstance,
    PHONECALLBACK lpfnCallback,
    LPCWSTR lpszFriendlyAppName,
    DWORD* lpdwNumDevs,
    DWORD* lpdwAPIVersion,
    PHONEINITIALIZEEXPARAMS* lpPhoneInitializeExParams
);

[DllImport("TAPI32.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int phoneInitializeExW(
    ref uint lphPhoneApp,   // DWORD* in/out
    IntPtr hInstance,   // HINSTANCE
    IntPtr lpfnCallback,   // PHONECALLBACK
    [MarshalAs(UnmanagedType.LPWStr)] string lpszFriendlyAppName,   // LPCWSTR
    ref uint lpdwNumDevs,   // DWORD* in/out
    ref uint lpdwAPIVersion,   // DWORD* in/out
    IntPtr lpPhoneInitializeExParams   // PHONEINITIALIZEEXPARAMS* in/out
);

<DllImport("TAPI32.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function phoneInitializeExW(
    ByRef lphPhoneApp As UInteger,   ' DWORD* in/out
    hInstance As IntPtr,   ' HINSTANCE
    lpfnCallback As IntPtr,   ' PHONECALLBACK
    <MarshalAs(UnmanagedType.LPWStr)> lpszFriendlyAppName As String,   ' LPCWSTR
    ByRef lpdwNumDevs As UInteger,   ' DWORD* in/out
    ByRef lpdwAPIVersion As UInteger,   ' DWORD* in/out
    lpPhoneInitializeExParams As IntPtr   ' PHONEINITIALIZEEXPARAMS* in/out
) As Integer
End Function

' lphPhoneApp : DWORD* in/out
' hInstance : HINSTANCE
' lpfnCallback : PHONECALLBACK
' lpszFriendlyAppName : LPCWSTR
' lpdwNumDevs : DWORD* in/out
' lpdwAPIVersion : DWORD* in/out
' lpPhoneInitializeExParams : PHONEINITIALIZEEXPARAMS* in/out
Declare PtrSafe Function phoneInitializeExW Lib "tapi32" ( _
    ByRef lphPhoneApp As Long, _
    ByVal hInstance As LongPtr, _
    ByVal lpfnCallback As LongPtr, _
    ByVal lpszFriendlyAppName As LongPtr, _
    ByRef lpdwNumDevs As Long, _
    ByRef lpdwAPIVersion As Long, _
    ByVal lpPhoneInitializeExParams 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

phoneInitializeExW = ctypes.windll.tapi32.phoneInitializeExW
phoneInitializeExW.restype = ctypes.c_int
phoneInitializeExW.argtypes = [
    ctypes.POINTER(wintypes.DWORD),  # lphPhoneApp : DWORD* in/out
    wintypes.HANDLE,  # hInstance : HINSTANCE
    ctypes.c_void_p,  # lpfnCallback : PHONECALLBACK
    wintypes.LPCWSTR,  # lpszFriendlyAppName : LPCWSTR
    ctypes.POINTER(wintypes.DWORD),  # lpdwNumDevs : DWORD* in/out
    ctypes.POINTER(wintypes.DWORD),  # lpdwAPIVersion : DWORD* in/out
    ctypes.c_void_p,  # lpPhoneInitializeExParams : PHONEINITIALIZEEXPARAMS* in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('TAPI32.dll')
phoneInitializeExW = Fiddle::Function.new(
  lib['phoneInitializeExW'],
  [
    Fiddle::TYPE_VOIDP,  # lphPhoneApp : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # hInstance : HINSTANCE
    Fiddle::TYPE_VOIDP,  # lpfnCallback : PHONECALLBACK
    Fiddle::TYPE_VOIDP,  # lpszFriendlyAppName : LPCWSTR
    Fiddle::TYPE_VOIDP,  # lpdwNumDevs : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # lpdwAPIVersion : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # lpPhoneInitializeExParams : PHONEINITIALIZEEXPARAMS* in/out
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "tapi32")]
extern "system" {
    fn phoneInitializeExW(
        lphPhoneApp: *mut u32,  // DWORD* in/out
        hInstance: *mut core::ffi::c_void,  // HINSTANCE
        lpfnCallback: *const core::ffi::c_void,  // PHONECALLBACK
        lpszFriendlyAppName: *const u16,  // LPCWSTR
        lpdwNumDevs: *mut u32,  // DWORD* in/out
        lpdwAPIVersion: *mut u32,  // DWORD* in/out
        lpPhoneInitializeExParams: *mut PHONEINITIALIZEEXPARAMS  // PHONEINITIALIZEEXPARAMS* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("TAPI32.dll", CharSet = CharSet.Unicode)]
public static extern int phoneInitializeExW(ref uint lphPhoneApp, IntPtr hInstance, IntPtr lpfnCallback, [MarshalAs(UnmanagedType.LPWStr)] string lpszFriendlyAppName, ref uint lpdwNumDevs, ref uint lpdwAPIVersion, IntPtr lpPhoneInitializeExParams);
"@
$api = Add-Type -MemberDefinition $sig -Name 'TAPI32_phoneInitializeExW' -Namespace Win32 -PassThru
# $api::phoneInitializeExW(lphPhoneApp, hInstance, lpfnCallback, lpszFriendlyAppName, lpdwNumDevs, lpdwAPIVersion, lpPhoneInitializeExParams)

#uselib "TAPI32.dll"
#func global phoneInitializeExW "phoneInitializeExW" wptr, wptr, wptr, wptr, wptr, wptr, wptr
; phoneInitializeExW varptr(lphPhoneApp), hInstance, lpfnCallback, lpszFriendlyAppName, varptr(lpdwNumDevs), varptr(lpdwAPIVersion), varptr(lpPhoneInitializeExParams)   ; 戻り値は stat
; lphPhoneApp : DWORD* in/out -> "wptr"
; hInstance : HINSTANCE -> "wptr"
; lpfnCallback : PHONECALLBACK -> "wptr"
; lpszFriendlyAppName : LPCWSTR -> "wptr"
; lpdwNumDevs : DWORD* in/out -> "wptr"
; lpdwAPIVersion : DWORD* in/out -> "wptr"
; lpPhoneInitializeExParams : PHONEINITIALIZEEXPARAMS* in/out -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "TAPI32.dll"
#cfunc global phoneInitializeExW "phoneInitializeExW" var, sptr, sptr, wstr, var, var, var
; res = phoneInitializeExW(lphPhoneApp, hInstance, lpfnCallback, lpszFriendlyAppName, lpdwNumDevs, lpdwAPIVersion, lpPhoneInitializeExParams)
; lphPhoneApp : DWORD* in/out -> "var"
; hInstance : HINSTANCE -> "sptr"
; lpfnCallback : PHONECALLBACK -> "sptr"
; lpszFriendlyAppName : LPCWSTR -> "wstr"
; lpdwNumDevs : DWORD* in/out -> "var"
; lpdwAPIVersion : DWORD* in/out -> "var"
; lpPhoneInitializeExParams : PHONEINITIALIZEEXPARAMS* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "TAPI32.dll"
#cfunc global phoneInitializeExW "phoneInitializeExW" sptr, sptr, sptr, wstr, sptr, sptr, sptr
; res = phoneInitializeExW(varptr(lphPhoneApp), hInstance, lpfnCallback, lpszFriendlyAppName, varptr(lpdwNumDevs), varptr(lpdwAPIVersion), varptr(lpPhoneInitializeExParams))
; lphPhoneApp : DWORD* in/out -> "sptr"
; hInstance : HINSTANCE -> "sptr"
; lpfnCallback : PHONECALLBACK -> "sptr"
; lpszFriendlyAppName : LPCWSTR -> "wstr"
; lpdwNumDevs : DWORD* in/out -> "sptr"
; lpdwAPIVersion : DWORD* in/out -> "sptr"
; lpPhoneInitializeExParams : PHONEINITIALIZEEXPARAMS* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。