phoneInitialize 関数 (tapi.h)

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

phoneInitialize 関数は廃止されました。 TAPI バージョン 1.3 および 1.4 を使用するアプリケーションとの下位互換性のために、Tapi.dll および Tapi32.dll によって引き続きエクスポートされます。

TAPI バージョン 2.0 以降を使用するアプリケーションでは、代わりに phoneInitializeEx を使用する必要があります。

TAPI バージョン 1.4 以前の場合: phoneInitialize 関数は、テレフォニー API での電話機能の後続の使用のために、アプリケーションによる TAPI の使用を初期化します。アプリケーションの指定された通知メカニズムを登録し、アプリケーションで使用できる電話デバイスの数を返します。

構文

LONG phoneInitialize(
  LPHPHONEAPP   lphPhoneApp,
  HINSTANCE     hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR        lpszAppName,
  LPDWORD       lpdwNumDevs
);

パラメーター

lphPhoneApp

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

hInstance

クライアントアプリケーションまたは DLL のインスタンスハンドル。

lpfnCallback

電話デバイスの状態とイベントを決定するために呼び出されるコールバック関数のアドレス。

lpszAppName

表示可能な文字を含む null で終わる文字列へのポインター。このパラメーターが NULL 以外の場合は、アプリケーション指定のアプリケーション名が含まれます。この名前は、電話デバイスの現在の所有者であるアプリケーションをわかりやすい方法で示すために、 PHONESTATUS 構造体に指定されます。この情報は、ログ記録と状態レポートの目的で役立ちます。 lpszAppName が NULL の場合は、代わりにアプリケーションのファイル名が使用されます。

lpdwNumDevs

DWORD へのポインター。この場所には、アプリケーションで使用できる電話デバイスの数が読み込まれます。

戻り値

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

PHONEERR_INVALAPPNAME、PHONEERR_INIFILECORRUPT、PHONEERR_INVALPOINTER、PHONEERR_NOMEM、PHONEERR_OPERATIONFAILED、PHONEERR_REINIT、PHONEERR_RESOURCEUNAVAIL、PHONEERR_NODEVICE、PHONEERR_NODRIVER、PHONEERR_INVALPARAM

注釈

アプリケーションは、0 から dwNumDevs から 1 を引いた範囲の電話デバイス識別子を使用して、個々の電話デバイスを参照できます。アプリケーションでは、これらの電話デバイスが、最初に phoneGetDevCaps 関数を使用してデバイスの機能に対してクエリを実行せずに、アシストテレフォニーサブセットで指定されているもの以外の機能が可能であると想定しないでください。

アプリケーションで phoneInitialize を呼び出すには、その後電話を開かないようにする必要があります (少なくとも監視用)。アプリケーションが監視されておらず、デバイスを使用していない場合は、不要な場合に TAPI によって割り当てられたメモリリソースを解放できるように phoneShutdown を呼び出し、TAPI 自体を不要な状態でメモリからアンロードできるようにする必要があります。

phoneShutdown を実行するもう 1 つの理由は、ユーザーがデバイスの構成を変更 (回線または電話を追加または削除) した場合、TAPI が、その時点で回線または電話ハンドルが開いているアプリケーションに通知する方法が存在しないということです。再構成が行われ、PHONESTATE_REINIT メッセージが送信された後、すべてのアプリケーションが phoneShutdown を実行するまで、アプリケーションはデバイスを開けなくなります。

サービスプロバイダーが正しく初期化できない場合、 phoneInitialize 関数は失敗し、サービスプロバイダーによって示されるエラーを返します。 PHONEERR_INVALPARAMエラー値が返された場合、指定された hInstance パラメーターは無効です。