lineInitializeExA

関数

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

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

シグネチャ

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

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

パラメーター

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

戻り値の型: INT

公式ドキュメント

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

戻り値

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

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

解説(Remarks)

アプリケーションは、TAPI がテレフォニーイベントをアプリケーションに通知するための 3 つのメカニズム (隠しウィンドウ、イベントハンドル、完了ポート) のいずれかを選択する必要があります。

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

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

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

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

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

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

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

メモ

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

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

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

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

import ctypes
from ctypes import wintypes

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

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

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

出力引数:

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