phoneInitializeExA 関数 (tapi.h)

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

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

構文

LONG phoneInitializeExA(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCSTR                    lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

パラメーター

lphPhoneApp

TAPI 用のアプリケーションの使用ハンドルが格納されている場所へのポインター。

hInstance

クライアントアプリケーションまたは DLL のインスタンスハンドル。アプリケーションまたは DLL は、このパラメーターに NULL を 渡すことができます。この場合、TAPI はプロセスのルート実行可能ファイルのモジュールハンドルを使用します。

lpfnCallback

アプリケーションがイベント通知の "非表示ウィンドウ" メソッドを使用している場合に、回線デバイス、アドレス、または呼び出しの状態とイベントを決定するために呼び出されるコールバック関数のアドレス (詳細については、「 phoneCallbackFunc」を参照してください)。このパラメーターは無視され、アプリケーションが "イベントハンドル" または "完了ポート" イベント通知メカニズムを使用することを選択した場合は NULL に 設定する必要があります。

lpszFriendlyAppName

表示可能な文字のみを含む null で終わる文字列へのポインター。このパラメーターが NULL でない場合は、アプリケーションに指定されたアプリケーション名が含まれます。この名前は PHONESTATUS 構造体で提供され、どのアプリケーションが電話デバイスの所有権を持つのかをわかりやすい方法で示します。 lpszFriendlyAppName が NULL の場合、アプリケーションのモジュールファイル名が代わりに使用されます (GetModuleFileName 関数によって返されます)。

lpdwNumDevs

DWORD へのポインター。この要求が正常に完了すると、この場所にはアプリケーションで使用できる電話デバイスの数が入力されます。

lpdwAPIVersion

DWORD へのポインター。アプリケーションは、この関数を呼び出す前に、この DWORD を、サポートするように設計された最高の API バージョン (たとえば、phoneNegotiateAPIVersion の dwAPIHighVersion パラメーターに渡されるのと同じ値) に初期化する必要があります。人為的に高い値を使用することはできません。値は正確に設定する必要があります。 TAPI は、新しいメッセージまたは構造体を、アプリケーションのバージョンでサポートされている値または形式に変換します。この要求が正常に完了すると、この場所には TAPI でサポートされている最高の API バージョンが入力されるため、アプリケーションは古いバージョンの TAPI を使用してシステムにインストールされたことを検出して適応できます。

lpPhoneInitializeExParams

アプリケーションと TAPI の間の関連付けを確立するために使用される追加のパラメーターを含む PHONEINITIALIZEEXPARAMS 型の構造体へのポインター (具体的には、アプリケーションで選択されたイベント通知メカニズムと関連するパラメーター)。

戻り値

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

PHONEERR_INVALAPPNAME、PHONEERR_OPERATIONFAILED、PHONEERR_INIFILECORRUPT、PHONEERR_INVALPOINTER、PHONEERR_REINIT、PHONEERR_NOMEM、PHONEERR_INVALPARAM。

注釈

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

非表示ウィンドウ メカニズムは、PHONEINITIALIZEEXPARAMS 構造体の dwOptions メンバーにPHONEINITIALIZEEXOPTION_USEHIDDENWINDOWを指定することによって選択されます。このメカニズムでは (TAPI バージョン 1 で使用できる唯一のメカニズムです。x アプリケーション)、TAPI は phoneInitializeEx 関数の間にアプリケーションのコンテキストでウィンドウを作成し、そのウィンドウに投稿されたすべてのメッセージが TAPI 自体の WNDPROC によって処理されるようにウィンドウをサブクラス化します。 TAPI にアプリケーションに配信するメッセージがある場合、TAPI は非表示ウィンドウにメッセージを投稿します。メッセージが受信されると (アプリケーションが Windows GetMessage 関数を呼び出した場合にのみ発生する可能性があります)、Windows はプロセスコンテキストをアプリケーションのコンテキストに切り替え、TAPI で WNDPROC を呼び出します。 TAPI は、 phoneCallbackFunc を呼び出してメッセージを配信します。これは、 phoneInitializeEx (TAPI バージョン 1.3 および 1.4 アプリケーションの場合は phoneInitialize) の呼び出しでアプリケーションがパラメーターとして指定したポインターです。このメカニズムを使用するには、アプリケーションにメッセージキュー (サービスプロセスでは望ましくない) と、テレフォニーイベントの処理の遅延を回避するために、そのキューに定期的にサービスを提供する必要があります。非表示ウィンドウは、 phoneShutdown 関数中に TAPI によって破棄されます。
イベントハンドル メカニズムは、PHONEINITIALIZEEXPARAMS 構造体の dwOptions メンバーにPHONEINITIALIZEEXOPTION_USEEVENTを指定することによって選択されます。このメカニズムでは、TAPI はアプリケーションに代わってイベントオブジェクトを作成し、PHONEINITIALIZEEXPARAMS の hEvent メンバー内のオブジェクトへのハンドルを返します。アプリケーションでは、このイベントを任意の方法で操作することはできません (たとえば、 SetEvent、 ResetEvent、 CloseHandle などを呼び出す必要があります)、または未定義の動作の結果。アプリケーションは、 WaitForSingleObject や MsgWaitForMultipleObjects などの関数を使用してのみ、このイベントを待機できます。 TAPI は、テレフォニーイベント通知がアプリケーションに対して保留中の場合に、このイベントを通知します。アプリケーションは phoneGetMessage を呼び出して、メッセージの内容をフェッチする必要があります。イベントが保留中でない場合、TAPI によってイベントがリセットされます。イベントハンドルが閉じられ、 phoneShutdown 関数中に TAPI によって破棄されたイベントオブジェクト。アプリケーションは、作成されたイベントハンドルを待機する必要はありません。アプリケーションは代わりに phoneGetMessage を呼び出し、メッセージのキューへの待機をブロックするように選択できます。
完了ポート メカニズムは、PHONEINITIALIZEEXPARAMS 構造体の dwOptions メンバーで PHONEINITIALIZEEXOPTION_USECOMPLETION PORT を指定することによって選択されます。このメカニズムでは、テレフォニーイベントをアプリケーションに送信する必要がある場合は常に、TAPI は PostQueuedCompletionStatus を使用してアプリケーションに送信し、PHONEINITIALIZEEXPARAMS の hCompletionPort メンバーで指定された完了ポートに、アプリケーションが PHONEINITIALIZEEXPARAMS の dwCompletionKey メンバーで指定した完了キーでタグ付けされます。アプリケーションでは、 CreateIoCompletionPort を使用して完了ポートを以前に作成しておく必要があります。アプリケーションは、 GetQueuedCompletionStatus を使用してイベントを取得します。 GetQueuedCompletionStatus から戻ると、アプリケーションには、lpCompletionKey パラメーターが指す DWORD に書き込まれた指定された dwCompletionKey と、lpOverlapped が指す場所に返される PHONEMESSAGE 構造体へのポインターがあります。アプリケーションがイベントを処理した後、アプリケーションは LocalFree を呼び出して 、PHONEMESSAGE 構造体を格納するために使用されるメモリを解放する必要があります。アプリケーションが完了ポートを作成したため (そのため、他の目的で共有できるようにする)、アプリケーションはそれを閉じる必要があります。アプリケーションは、phoneShutdown を呼び出すまで完了ポートを閉じてはなりません。

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

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

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

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

注意

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