lineInitializeExA 関数 (tapi.h)

[アーティクル]
03/08/2023

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 サイズの場所へのポインター。アプリケーションでは、この関数を呼び出す前に、サポートするように設計された最高の API バージョン (たとえば、lineNegotiateAPIVersion の dwAPIHighVersion パラメーターに渡されるのと同じ値) に、この DWORD を初期化する必要があります。人為的に高い値は使用しないでください。値を正確に設定する必要があります。 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 の再初期化が要求された場合、最後のアプリケーションが API の使用をシャットダウン (lineShutdown を使用) するまで、lineInitializeEx 要求はこのエラーで拒否されます。この時点で、新しい構成が有効になり、アプリケーションで lineInitializeEx の呼び出しが再度許可されます。

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

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

注意

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