lineInitializeExA 関数 (tapi.h)

[アーティクル]
03/02/2024

lineInitializeEx 関数は、行抽象化の後続の使用のために、アプリケーションによる TAPI の使用を初期化します。アプリケーションの指定された通知メカニズムを登録し、アプリケーションで使用できる回線デバイスの数を返します。回線デバイスは、テレフォニー API の行プレフィックス付き関数の実装を提供する任意のデバイスです。

構文

LONG lineInitializeExA(
  LPHLINEAPP               lphLineApp,
  HINSTANCE                hInstance,
  LINECALLBACK             lpfnCallback,
  LPCSTR                   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 メンバーに port LINEINITIALIZEEXOPTION_USECOMPLETION指定することによって選択されます。このメカニズムでは、テレフォニーイベントをアプリケーションに送信する必要がある場合、TAPI は PostQueuedCompletionStatus を使用して、LINEINITIALIZEEXPARAMS の hCompletionPort メンバーで指定された完了ポートに、アプリケーションが LINEINITIALIZEEXPARAMS の dwCompletionKey メンバーで指定した完了キーでタグ付けして送信します。アプリケーションでは、 CreateIoCompletionPort を使用して完了ポートを以前に作成しておく必要があります。アプリケーションは、 GetQueuedCompletionStatus を使用してイベントを取得します。 GetQueuedCompletionStatus から戻ると、アプリケーションは lpCompletionKey パラメーターによって指される DWORD に書き込まれた指定された dwCompletionKey と、lpOverlapped によって指される場所に返される LINEMESSAGE 構造体へのポインターを持ちます。アプリケーションがイベントを処理した後、アプリケーションは LocalFree を呼び出して 、LINEMESSAGE 構造体を格納するために使用されるメモリを解放する必要があります。アプリケーションが完了ポートを作成したため (これにより、他の目的で共有できるようにする)、アプリケーションはそれを閉じる必要があります。 lineShutdown を呼び出すまで、アプリケーションは完了ポートを閉じてはいけません。

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

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

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

アプリケーションは、0 から dwNumDevs から 1 を引いた範囲の回線デバイス識別子を使用して、個々の回線デバイスを参照できます。アプリケーションでは、最初に lineGetDevCaps と lineGetAddressCaps によってデバイスの機能に対してクエリを実行せずに、これらの回線デバイスが特定の TAPI 関数に対応していると想定しないでください。

注意

tapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして lineInitializeEx を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイルエラーまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。