TSPI_lineMonitorTones関数 (tspi.h)

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

TSPI_lineMonitorTones関数は、呼び出しのインバンドトーンの検出を有効または無効にします。指定したトーンが検出されるたびに、TAPI を介してメッセージがクライアントアプリケーションに送信されます。

構文

LONG TSPIAPI TSPI_lineMonitorTones(
  HDRVCALL                hdCall,
  DWORD                   dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD                   dwNumEntries
);

パラメーター

hdCall

トーン検出を実行する呼び出しへのハンドル。 hdCall の呼び出し状態は、アイドル状態を除く任意の状態にすることができます。

dwToneListID

このトーンリストの一意識別子。一度に複数のトーンリストを未処理にすることができます。サービスプロバイダーは、同じ dwToneListID を持つ古いリストを新しいトーンリストに置き換える必要があります。 lpToneList が NULL の場合、dwToneListID を持つトーンリストは単に削除されます。いずれの場合も、 dwToneListIDが異なる他のトーンリストは変更されません。

lpToneList

監視するトーンの一覧 ( LINEMONITORTONE 型)。このリストの各トーンには、トーン検出を報告するためにリスト内の個々のトーンを識別するために使用されるアプリケーション定義のタグフィールドがあります。進行中のトーン監視は、lpToneList の場合は NULL、または別のトーンリストを使用してこの操作を呼び出すことによってキャンセルまたは変更されます。サービスプロバイダーは、単にポインターをアプリケーションメモリに保持するのではなく、後で参照するためにトーンリストを独自のメモリにコピーする必要があります。

dwNumEntries

lpToneList 内のエントリの数。 lpToneList が NULL の場合、dwNumEntries パラメーターは無視されます。 TAPI は、この関数が呼び出されたときにこのパラメーターを検証しません。

戻り値

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

LINEERR_INVALCALLHANDLE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALCALLSTATE、LINEERR_OPERATIONFAILED、LINEERR_INVALTONE、LINEERR_RESOURCEUNAVAIL、LINEERR_NOMEM、LINEERR_INVALPOINTER。

注釈

この関数は、トーン監視が終了したときではなく、トーン監視が正しく開始されると 0 (成功) を返します。メディア監視と同様に、同じ dwToneListID と別のトーンリスト (または NULL トーンリスト) を使用してTSPI_lineMonitorTonesを呼び出すか、呼び出しがアイドル状態に移行するまで、特定のトーンリストに対するトーン監視は有効なままです。

この関数は アイドル状態を除く任意の呼び出し状態で呼び出すことができますが、通常、トーンは呼び出しが接続状態の間にのみ検出できます。トーン検出には通常、計算リソースが必要です。このようなリソースを競合するサービスプロバイダーやその他のアクティビティによっては、検出できるトーンの数が時間の経過と同時に異なる場合があります。また、1 つの 3 つの周波数トーンと 3 つの単一周波数トーンを監視するために、同等の量のリソースを使用できます。リソースがオーバーコミットされた場合、サービスプロバイダーはLINEERR_RESOURCEUNAVAILを返します。

サービスプロバイダーは、すべてのトーンリスト内のすべてのトーンを同時に監視します。トーンが検出されると、各トーンリストの一致する各トーンが、LINE_MONITORTONE メッセージを使用して個別に報告されます。各トーンレポートには、トーンリスト識別子とアプリケーション固有のタグの両方が含まれます。一部のサービスプロバイダーでは、非常に近いトーンを区別できない場合があるため、説明が厳密に同じではないトーンでも複数の一致が報告される可能性があります。

TSPI_lineMonitorTonesは無音を検出するためにも使用されます。無音は、すべてのゼロ周波数を持つトーンとして指定されます。

TAPI レベルの対応する関数には 、dwToneListID パラメーターは含まれません。 TSPI インターフェイスにこのパラメーターを含めることにより、TAPI は、すべてのアプリケーションからサービスプロバイダーにすべてのトーン監視リストの和集合を転送しながら、アプリケーションに従ってトーン検出イベントをフィルター処理および転送する機能を維持できます。これにより、TAPI はトーンの説明が同一と見なされる前提がないため、サービスプロバイダーデザイナーは非常に近いトーンを判別できる程度を決定する最大の柔軟性を提供します。