lineInitializeEx 関数は、アプリケーションによる TAPI の使用を初期化して、後続の行抽象化を使用します。 アプリケーションの指定された通知メカニズムを登録し、アプリケーションで使用できる回線デバイスの数を返します。 回線デバイスは、テレフォニー API の行プレフィックス付き関数の実装を提供する任意のデバイスです。
構文
LONG lineInitializeExW(
LPHLINEAPP lphLineApp,
HINSTANCE hInstance,
LINECALLBACK lpfnCallback,
LPCWSTR lpszFriendlyAppName,
LPDWORD lpdwNumDevs,
LPDWORD lpdwAPIVersion,
LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);
パラメーター
lphLineApp
TAPI 用のアプリケーションの使用ハンドルが格納されている場所へのポインター。
hInstance
クライアント アプリケーションまたは DLL のインスタンス ハンドル。 アプリケーションまたは DLL は、このパラメーターに NULL を 渡すことができます。この場合、TAPI はプロセスのルート実行可能ファイルのモジュール ハンドルを使用します (呼び出しハンドオフ ターゲットとメディア モードの優先順位を識別するため)。
lpfnCallback
アプリケーションがイベント通知の "非表示ウィンドウ" メソッドを使用している場合に、ライン デバイス、アドレス、または呼び出しの状態とイベントを判断するために呼び出されるコールバック関数のアドレス (詳細については、「 lineCallbackFunc」を参照してください)。 このパラメーターは無視され、アプリケーションが "イベント ハンドル" または "完了ポート" イベント通知メカニズムを使用することを選択した場合は NULL に 設定する必要があります。
lpszFriendlyAppName
表示可能な文字のみを含む null で終わるテキスト文字列へのポインター。 このパラメーターが NULL でない場合は、アプリケーションに指定されたアプリケーション名が含まれます。 この名前は 、LINECALLINFO 構造体で提供され、アプリケーションの発信元、または最初に受け入れられたか、または呼び出しに応答したかをわかりやすい方法で示します。 この情報は、呼び出しログの目的で役立ちます。 lpszFriendlyAppName が NULL の場合は、アプリケーションのモジュール ファイル名が代わりに使用されます (GetModuleFileName 関数によって返されます)。
lpdwNumDevs
DWORD サイズの場所へのポインター。 この要求が正常に完了すると、この場所には、アプリケーションで使用できる回線デバイスの数が入力されます。
lpdwAPIVersion
DWORD サイズの場所へのポインター。 アプリケーションは、この関数を呼び出す前に、この DWORD を、サポートするように設計されている最高の API バージョン (たとえば、lineNegotiateAPIVersion の dwAPIHighVersion パラメーターに渡されるのと同じ値) に初期化する必要があります。 人為的に高い値を使用することはできません。値は正確に設定する必要があります。 TAPI は、新しいメッセージまたは構造体を、アプリケーションのバージョンでサポートされている値または形式に変換します。 この要求が正常に完了すると、この場所には TAPI でサポートされている最高の API バージョンが入力されるため、アプリケーションは、別のバージョンの TAPI を持つシステムにインストールされたことを検出して適応できます。
lpLineInitializeExParams
アプリケーションと TAPI の間の関連付けを確立するために使用される追加のパラメーターを含む LINEINITIALIZEEXPARAMS 型の構造体へのポインター (具体的には、アプリケーションで選択されたイベント通知メカニズムと関連パラメーター)。
戻り値
要求が成功した場合は 0 を返し、エラーが発生した場合は負のエラー番号を返します。 可能な戻り値は次のとおりです。
LINEERR_INVALAPPNAME、LINEERR_OPERATIONFAILED、LINEERR_INIFILECORRUPT、LINEERR_INVALPOINTER、LINEERR_REINIT、LINEERR_NOMEM、LINEERR_INVALPARAM。
解説
アプリケーションでは、TAPI がテレフォニー イベントをアプリケーションに通知する 3 つのメカニズム (非表示ウィンドウ、イベント ハンドル、または完了ポート) のいずれかを選択する必要があります。
非表示ウィンドウ 機構は、LINEINITIALIZEEXPARAMS 構造体の dwOptions メンバーにLINEINITIALIZEEXOPTION_USEHIDDENWINDOWを指定することによって選択されます。 このメカニズムでは (TAPI バージョン 1 で使用できる唯一のメカニズムです。x アプリケーション)、TAPI は、lineInitializeEx または lineInitialize (TAPI バージョン 1.3 および 1.4 アプリケーションの場合) 関数の間にアプリケーションのコンテキストでウィンドウを作成し、そのウィンドウに投稿されたすべてのメッセージが TAPI 自体の WNDPROC によって処理されるようにウィンドウをサブクラス化します。 TAPI にアプリケーションに配信するメッセージがある場合、TAPI は非表示ウィンドウにメッセージを投稿します。 メッセージが受信されると (アプリケーションが Windows GetMessage 関数を呼び出した場合にのみ発生する可能性があります)、Windows はプロセス コンテキストをアプリケーションのコンテキストに切り替え、TAPI で WNDPROC を呼び出します。 TAPI は、 lineCallbackProc ( lineInitializeEx (または lineInitialize) の呼び出しでアプリケーションがパラメーターとして指定したポインター) を呼び出して、アプリケーションにメッセージを配信します。 このメカニズムを使用するには、アプリケーションにメッセージ キュー (サービス プロセスでは望ましくない) と、テレフォニー イベントの処理の遅延を回避するために、そのキューに定期的にサービスを提供する必要があります。 隠しウィンドウは、 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 から戻ると、アプリケーションには、lpCompletionKey パラメーターが指す DWORD に書き込まれた指定された dwCompletionKey と、lpOverlapped が指す場所に返される LINEMESSAGE 構造体へのポインターがあります。 アプリケーションがイベントを処理した後、 アプリケーションは LocalFree を呼び出して 、LINEMESSAGE 構造体を格納するために使用されるメモリを解放する必要があります。 アプリケーションが完了ポートを作成したため (そのため、他の目的で共有できるようにする)、アプリケーションはそれを閉じる必要があります。 lineShutdown を呼び出すまで、アプリケーションは完了ポートを閉じてはなりません。
マルチスレッド アプリケーションがイベント ハンドル メカニズムを使用していて、複数のスレッドがハンドルで待機している場合、または完了ポート通知メカニズムで複数のスレッドがポートで待機している場合、テレフォニー イベントが順番に処理される可能性があります。 これは TAPI からのイベントの配信シーケンスによるものではありませんが、スレッドのタイム スライスまたは個別のプロセッサでのスレッドの実行が原因で発生します。
LINEERR_REINITが返され、たとえばテレフォニー サービス プロバイダーを追加または削除した結果として TAPI の再初期化が要求された場合、 lineInitializeEx 要求は、最後のアプリケーションが API の使用をシャットダウンするまでこのエラーで拒否されます ( lineShutdown を使用)。その時点で新しい構成が有効になり、アプリケーションは lineInitializeEx を呼び出すのが再度許可されます。
LINEERR_INVALPARAMエラー値が返された場合、指定された hInstance パラメーターは無効です。
アプリケーションは、0 から dwNumDevs から 1 を引いた範囲の回線デバイス識別子を使用して、個々の回線デバイスを参照できます。 アプリケーションでは、最初に lineGetDevCaps と lineGetAddressCaps によってデバイスの機能に対してクエリを実行せずに、これらの 回線デバイスが特定の TAPI 関数に対応していると想定しないでください。
注意
tapi.h ヘッダーは、LINEInitializeEx をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 対象プラットフォーム | Windows |
| ヘッダー | tapi.h |
| Library | Tapi32.lib |
| [DLL] | Tapi32.dll |