lineInitializeExW

関数

拡張パラメータ付きでTAPIを初期化する(Unicode版)。

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

シグネチャ

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

INT lineInitializeExW(
    DWORD* lphLineApp,
    HINSTANCE hInstance,
    LINECALLBACK lpfnCallback,
    LPCWSTR lpszFriendlyAppName,
    DWORD* lpdwNumDevs,
    DWORD* lpdwAPIVersion,
    LINEINITIALIZEEXPARAMS* lpLineInitializeExParams
);

パラメーター

名前	型	方向	説明
lphLineApp	DWORD*	inout	TAPI に対するアプリケーションの使用ハンドルが格納される場所へのポインターです。
hInstance	HINSTANCE	in	クライアントアプリケーションまたは DLL のインスタンスハンドルです。アプリケーションまたは DLL はこのパラメーターに NULL を渡すことができます。その場合、TAPI は(通話のハンドオフ先とメディアモードの優先順位を識別する目的で)プロセスのルート実行可能ファイルのモジュールハンドルを使用します。
lpfnCallback	LINECALLBACK	in	アプリケーションがイベント通知に「隠しウィンドウ」方式を使用する場合に、line デバイス、アドレス、または通話の状態やイベントを判別するために呼び出されるコールバック関数のアドレスです(詳細については lineCallbackFunc を参照してください)。アプリケーションが「イベントハンドル」または「完了ポート」のイベント通知メカニズムを選択する場合、このパラメーターは無視されるため NULL を設定してください。
lpszFriendlyAppName	LPCWSTR	in	表示可能な文字のみを含む null 終端のテキスト文字列へのポインターです。このパラメーターが NULL でない場合は、アプリケーションが指定したそのアプリケーションの名前を含みます。この名前は LINECALLINFO 構造体で提供され、どのアプリケーションがその通話を発信したか、あるいは最初に受け入れたか応答したかを、ユーザーにとって分かりやすい形で示します。この情報は通話ログの記録に役立ちます。lpszFriendlyAppName が NULL の場合は、代わりにアプリケーションのモジュールファイル名(GetModuleFileName 関数が返す値)が使用されます。
lpdwNumDevs	DWORD*	inout	DWORD サイズの場所へのポインターです。この要求が正常に完了すると、この場所にはアプリケーションが利用できる line デバイスの数が格納されます。
lpdwAPIVersion	DWORD*	inout	DWORD サイズの場所へのポインターです。アプリケーションはこの関数を呼び出す前に、この DWORD に、自身がサポートするように設計された最も高い API バージョン(たとえば lineNegotiateAPIVersion の dwAPIHighVersion パラメーターに渡すのと同じ値)を設定して初期化する必要があります。不自然に高い値を使用してはならず、値は正確に設定する必要があります。TAPI は、より新しいメッセージや構造体を、アプリケーションのバージョンでサポートされる値や形式に変換します。この要求が正常に完了すると、この場所には TAPI がサポートする最も高い API バージョンが格納されます。これにより、アプリケーションは異なるバージョンの TAPI を持つシステムにインストールされたことを検出し、それに適応できます。
lpLineInitializeExParams	LINEINITIALIZEEXPARAMS*	inout	アプリケーションと TAPI の間の関連付けを確立するために使用する追加のパラメーター(具体的には、アプリケーションが選択したイベント通知メカニズムと関連パラメーター)を格納した LINEINITIALIZEEXPARAMS 型の構造体へのポインターです。

戻り値の型: INT

公式ドキュメント

lineInitializeEx 関数は、その後 line 抽象化を使用するために、アプリケーションによる TAPI の使用を初期化します。(Unicode)

戻り値

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

LINEERR_INVALAPPNAME、LINEERR_OPERATIONFAILED、LINEERR_INIFILECORRUPT、LINEERR_INVALPOINTER、LINEERR_REINIT、LINEERR_NOMEM、LINEERR_INVALPARAM。

解説(Remarks)

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

Hidden Window メカニズムは、LINEINITIALIZEEXPARAMS 構造体の dwOptions メンバーに LINEINITIALIZEEXOPTION_USEHIDDENWINDOW を指定することで選択します。このメカニズム(TAPI バージョン 1.x のアプリケーションで利用できる唯一のメカニズム)では、TAPI は lineInitializeEx 関数(TAPI バージョン 1.3 および 1.4 のアプリケーションでは lineInitialize 関数)の実行中に、アプリケーションのコンテキストでウィンドウを作成し、そのウィンドウをサブクラス化して、ポストされるすべてのメッセージが TAPI 自身の WNDPROC で処理されるようにします。TAPI はアプリケーションに配信するメッセージがあると、その隠しウィンドウにメッセージをポストします。メッセージが受信されると(これはアプリケーションが Windows の GetMessage 関数を呼び出したときにのみ発生します)、Windows はプロセスコンテキストをアプリケーションのものに切り替え、TAPI 内の WNDPROC を呼び出します。続いて TAPI は、アプリケーションが lineInitializeEx(または lineInitialize)の呼び出し時にパラメーターとしてポインターを指定した lineCallbackProc を呼び出して、メッセージをアプリケーションに配信します。このメカニズムでは、アプリケーションがメッセージキューを持つ必要があり(サービスプロセスにとっては望ましくありません)、テレフォニーイベントの処理が遅れないように、そのキューを定期的に処理する必要があります。隠しウィンドウは、lineShutdown 関数の実行中に TAPI によって破棄されます。

Event Handle メカニズムは、LINEINITIALIZEEXPARAMS 構造体の dwOptions メンバーに LINEINITIALIZEEXOPTION_USEEVENT を指定することで選択します。このメカニズムでは、TAPI はアプリケーションの代わりにイベントオブジェクトを作成し、そのオブジェクトのハンドルを LINEINITIALIZEEXPARAMS の hEvent メンバーに返します。アプリケーションはこのイベントをいかなる方法でも操作してはなりません(たとえば SetEvent、ResetEvent、CloseHandle などを呼び出してはなりません)。操作した場合の動作は未定義です。アプリケーションは WaitForSingleObject や MsgWaitForMultipleObjects などの関数を使ってこのイベントを待機することだけができます。TAPI は、アプリケーションに対するテレフォニーイベント通知が保留中になるたびに、このイベントをシグナル状態にします。アプリケーションは lineGetMessage を呼び出して、メッセージの内容を取得する必要があります。保留中のイベントがなくなると、TAPI がイベントをリセットします。イベントハンドルは、lineShutdown 関数の実行中に TAPI によって閉じられ、イベントオブジェクトも破棄されます。アプリケーションは、作成されたイベントハンドルを必ず待機しなければならないわけではありません。代わりに lineGetMessage を呼び出し、メッセージがキューに入るまでその中でブロックさせることもできます。

Completion Port メカニズムは、LINEINITIALIZEEXPARAMS 構造体の dwOptions メンバーに LINEINITIALIZEEXOPTION_USECOMPLETION PORT を指定することで選択します。このメカニズムでは、テレフォニーイベントをアプリケーションに送信する必要が生じるたびに、TAPI は PostQueuedCompletionStatus を使用して、アプリケーションが LINEINITIALIZEEXPARAMS の hCompletionPort メンバーで指定した完了ポートへ、アプリケーションが LINEINITIALIZEEXPARAMS の dwCompletionKey メンバーで指定した完了キーを付けてイベントを送信します。アプリケーションは、あらかじめ CreateIoCompletionPort を使用して完了ポートを作成しておく必要があります。アプリケーションは GetQueuedCompletionStatus を使用してイベントを取得します。GetQueuedCompletionStatus から戻ると、アプリケーションには lpCompletionKey パラメーターが指す DWORD に、指定した dwCompletionKey が書き込まれ、lpOverlapped が指す場所に LINEMESSAGE 構造体へのポインターが返されます。アプリケーションがイベントを処理した後、LINEMESSAGE 構造体を格納するために使用されたメモリを解放するために LocalFree を呼び出すのは、アプリケーションの責任です。完了ポートはアプリケーションが作成したものであるため(そのため他の目的にも共有できます)、アプリケーションがそれを閉じる必要があります。ただし、lineShutdown を呼び出すまでは完了ポートを閉じてはなりません。

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

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

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

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

メモ

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

出典・ライセンス: 上記「公式ドキュメント」の内容は 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 lineInitializeExW(
    DWORD* lphLineApp,
    HINSTANCE hInstance,
    LINECALLBACK lpfnCallback,
    LPCWSTR lpszFriendlyAppName,
    DWORD* lpdwNumDevs,
    DWORD* lpdwAPIVersion,
    LINEINITIALIZEEXPARAMS* lpLineInitializeExParams
);

[DllImport("TAPI32.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int lineInitializeExW(
    ref uint lphLineApp,   // DWORD* in/out
    IntPtr hInstance,   // HINSTANCE
    IntPtr lpfnCallback,   // LINECALLBACK
    [MarshalAs(UnmanagedType.LPWStr)] string lpszFriendlyAppName,   // LPCWSTR
    ref uint lpdwNumDevs,   // DWORD* in/out
    ref uint lpdwAPIVersion,   // DWORD* in/out
    IntPtr lpLineInitializeExParams   // LINEINITIALIZEEXPARAMS* in/out
);

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

' lphLineApp : DWORD* in/out
' hInstance : HINSTANCE
' lpfnCallback : LINECALLBACK
' lpszFriendlyAppName : LPCWSTR
' lpdwNumDevs : DWORD* in/out
' lpdwAPIVersion : DWORD* in/out
' lpLineInitializeExParams : LINEINITIALIZEEXPARAMS* in/out
Declare PtrSafe Function lineInitializeExW Lib "tapi32" ( _
    ByRef lphLineApp As Long, _
    ByVal hInstance As LongPtr, _
    ByVal lpfnCallback As LongPtr, _
    ByVal lpszFriendlyAppName As LongPtr, _
    ByRef lpdwNumDevs As Long, _
    ByRef lpdwAPIVersion As Long, _
    ByVal lpLineInitializeExParams 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

lineInitializeExW = ctypes.windll.tapi32.lineInitializeExW
lineInitializeExW.restype = ctypes.c_int
lineInitializeExW.argtypes = [
    ctypes.POINTER(wintypes.DWORD),  # lphLineApp : DWORD* in/out
    wintypes.HANDLE,  # hInstance : HINSTANCE
    ctypes.c_void_p,  # lpfnCallback : LINECALLBACK
    wintypes.LPCWSTR,  # lpszFriendlyAppName : LPCWSTR
    ctypes.POINTER(wintypes.DWORD),  # lpdwNumDevs : DWORD* in/out
    ctypes.POINTER(wintypes.DWORD),  # lpdwAPIVersion : DWORD* in/out
    ctypes.c_void_p,  # lpLineInitializeExParams : LINEINITIALIZEEXPARAMS* in/out
]

require 'fiddle'
require 'fiddle/import'

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

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

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

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

出力引数:

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