phoneInitializeExA 関数 (tapi.h)

[アーティクル]
11/20/2024

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

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

lpdwNumDevs

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

lpdwAPIVersion

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

lpPhoneInitializeExParams

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

戻り値

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

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

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

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

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

手記

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

必要条件

要件	価値
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	tapi.h
ライブラリ	Tapi32.lib
DLL	Tapi32.dll

次の方法で共有

phoneInitializeExA 関数 (tapi.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース