phoneInitializeExA

関数

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

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

シグネチャ

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

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

パラメーター

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

戻り値の型: INT

公式ドキュメント

phoneInitializeEx 関数は、以降の電話抽象化の使用に備えて、アプリケーションによる TAPI の使用を初期化します。(ANSI)

戻り値

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

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

解説(Remarks)

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

Hidden Window メカニズムは、 PHONEINITIALIZEEXPARAMS 構造体の dwOptions メンバーに PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW を指定することで選択します。このメカニズム (TAPI バージョン 1.x のアプリケーションで利用できる唯一のメカニズム) では、TAPI は phoneInitializeEx 関数の処理中にアプリケーションのコンテキストでウィンドウを作成し、そのウィンドウをサブクラス化して、ポストされたすべてのメッセージが TAPI 自身の WNDPROC で処理されるようにします。TAPI はアプリケーションに配信するメッセージがあると、隠しウィンドウにメッセージをポストします。メッセージが受信されると (これはアプリケーションが Windows の GetMessage 関数を呼び出したときにのみ発生します)、Windows はプロセスコンテキストをアプリケーションのものに切り替え、TAPI 内の WNDPROC を呼び出します。その後 TAPI は phoneCallbackFunc を呼び出してメッセージをアプリケーションに配信します。このコールバック関数へのポインターは、アプリケーションが phoneInitializeEx (TAPI バージョン 1.3 および 1.4 のアプリケーションの場合は phoneInitialize) を呼び出す際にパラメーターとして指定したものです。このメカニズムでは、アプリケーションがメッセージキューを持ち (これはサービスプロセスにとって望ましくありません)、テレフォニーイベントの処理が遅延しないように定期的にそのキューを処理する必要があります。隠しウィンドウは 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 から復帰すると、lpCompletionKey パラメーターが指す DWORD には指定された dwCompletionKey が書き込まれ、lpOverlapped が指す場所には PHONEMESSAGE 構造体へのポインターが返されます。アプリケーションはイベントを処理した後、 LocalFree を呼び出して PHONEMESSAGE 構造体に使用されていたメモリを解放する必要があります。完了ポートはアプリケーションが作成したものである (そのため他の目的にも共有できる) ため、アプリケーションが閉じる必要があります。ただし、 phoneShutdown を呼び出すまでは完了ポートを閉じてはなりません。

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

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

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

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

メモ

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

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

各言語での呼び出し定義

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

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

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

<DllImport("TAPI32.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function phoneInitializeExA(
    ByRef lphPhoneApp As UInteger,   ' DWORD* in/out
    hInstance As IntPtr,   ' HINSTANCE
    lpfnCallback As IntPtr,   ' PHONECALLBACK
    <MarshalAs(UnmanagedType.LPStr)> lpszFriendlyAppName As String,   ' LPCSTR
    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 : LPCSTR
' lpdwNumDevs : DWORD* in/out
' lpdwAPIVersion : DWORD* in/out
' lpPhoneInitializeExParams : PHONEINITIALIZEEXPARAMS* in/out
Declare PtrSafe Function phoneInitializeExA Lib "tapi32" ( _
    ByRef lphPhoneApp As Long, _
    ByVal hInstance As LongPtr, _
    ByVal lpfnCallback As LongPtr, _
    ByVal lpszFriendlyAppName As String, _
    ByRef lpdwNumDevs As Long, _
    ByRef lpdwAPIVersion As Long, _
    ByVal lpPhoneInitializeExParams As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

phoneInitializeExA = ctypes.windll.tapi32.phoneInitializeExA
phoneInitializeExA.restype = ctypes.c_int
phoneInitializeExA.argtypes = [
    ctypes.POINTER(wintypes.DWORD),  # lphPhoneApp : DWORD* in/out
    wintypes.HANDLE,  # hInstance : HINSTANCE
    ctypes.c_void_p,  # lpfnCallback : PHONECALLBACK
    wintypes.LPCSTR,  # lpszFriendlyAppName : LPCSTR
    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')
phoneInitializeExA = Fiddle::Function.new(
  lib['phoneInitializeExA'],
  [
    Fiddle::TYPE_VOIDP,  # lphPhoneApp : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # hInstance : HINSTANCE
    Fiddle::TYPE_VOIDP,  # lpfnCallback : PHONECALLBACK
    Fiddle::TYPE_VOIDP,  # lpszFriendlyAppName : LPCSTR
    Fiddle::TYPE_VOIDP,  # lpdwNumDevs : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # lpdwAPIVersion : DWORD* in/out
    Fiddle::TYPE_VOIDP,  # lpPhoneInitializeExParams : PHONEINITIALIZEEXPARAMS* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "tapi32")]
extern "system" {
    fn phoneInitializeExA(
        lphPhoneApp: *mut u32,  // DWORD* in/out
        hInstance: *mut core::ffi::c_void,  // HINSTANCE
        lpfnCallback: *const core::ffi::c_void,  // PHONECALLBACK
        lpszFriendlyAppName: *const u8,  // LPCSTR
        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.Ansi)]
public static extern int phoneInitializeExA(ref uint lphPhoneApp, IntPtr hInstance, IntPtr lpfnCallback, [MarshalAs(UnmanagedType.LPStr)] string lpszFriendlyAppName, ref uint lpdwNumDevs, ref uint lpdwAPIVersion, IntPtr lpPhoneInitializeExParams);
"@
$api = Add-Type -MemberDefinition $sig -Name 'TAPI32_phoneInitializeExA' -Namespace Win32 -PassThru
# $api::phoneInitializeExA(lphPhoneApp, hInstance, lpfnCallback, lpszFriendlyAppName, lpdwNumDevs, lpdwAPIVersion, lpPhoneInitializeExParams)

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

出力引数:

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