lineSetMediaControl 関数 (tapi.h)

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

lineSetMediaControl 関数は、指定した行、アドレス、または呼び出しに関連付けられているメディアストリームに対するコントロールアクションを有効または無効にします。メディア制御アクションは、指定した数字、メディアの種類、カスタムトーン、および呼び出し状態の検出によってトリガーできます。

構文

LONG lineSetMediaControl(
  HLINE                             hLine,
  DWORD                             dwAddressID,
  HCALL                             hCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

パラメーター

hLine

開いている回線デバイスへのハンドル。

dwAddressID

指定されたオープンラインデバイスのアドレス識別子。アドレス識別子は、アドレスに完全に関連付けられます。識別子は、オペレーティングシステムのアップグレード間で一定のままです。

hCall

呼び出しへのハンドル。アプリケーションは、呼び出しの所有者である必要があります。 hCall の呼び出し状態には、任意の状態を指定できます。

dwSelect

要求されたメディアコントロールが 1 つの呼び出しに関連付けられているかどうか、アドレスのすべての呼び出しの既定値、または行のすべての呼び出しの既定値です。このパラメーターは、 LINECALLSELECT_定数の 1 つだけです。

lpDigitList

LINEMEDIACONTROLDIGIT 型のメディア制御アクションをトリガーする桁数を含む配列へのポインター。数字リスト内の数字が検出されるたびに、指定されたメディア制御アクションが呼び出しのメディアストリームで実行されます。

パルスモードの有効な数字は、'0' から '9' です。 DTMF モードの有効な数字は、'0' から '9'、'A'、'B'、'C'、'D'、'*'、'#' です。

dwDigitNumEntries

lpDigitList 内のエントリの数。

lpMediaList

LINEMEDIACONTROLMEDIA 型のエントリを含む配列へのポインター。配列には dwMediaNumEntries エントリがあります。各エントリには、監視対象のメディアタイプ、メディアタイプ固有の情報(期間など)、およびメディア制御フィールドが含まれます。リスト内のメディアの種類が検出されると、対応するメディア制御アクションが呼び出しのメディアストリームに対して実行されます。

dwMediaNumEntries

lpMediaList のエントリの数。

lpToneList

LINEMEDIACONTROLTONE 型のエントリを含む配列へのポインター。配列には dwToneNumEntries エントリがあります。各エントリには、監視するトーン、トーンの継続時間、メディアコントロールフィールドの説明が含まれています。リスト内のトーンが検出されると、対応するメディア制御アクションが呼び出しのメディアストリームに対して実行されます。

dwToneNumEntries

lpToneList のエントリの数。

lpCallStateList

LINEMEDIACONTROLCALLSTATE 型のエントリを含む配列へのポインター。配列には dwCallStateNumEntries エントリがあります。各エントリには、通話状態とメディアコントロールアクションが含まれます。指定された呼び出しがリスト内のいずれかの呼び出し状態に遷移するたびに、対応するメディア制御アクションが呼び出されます。

dwCallStateNumEntries

lpCallStateList 内のエントリの数。

戻り値

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

LINEERR_INVALADDRESSID、LINEERR_NOMEM、LINEERR_INVALCALLHANDLE、LINEERR_NOTOWNER、LINEERR_INVALCALLSELECT、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALCALLSTATELIST、LINEERR_OPERATIONFAILED、LINEERR_INVALDIGITLIST、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALLINEHANDLE、LINEERR_UNINITIALIZED、LINEERR_INVALMEDIALIST、LINEERR_INVALPOINTER、LINEERR_INVALTONELIST。

注釈

lineSetMediaControl 関数は、メディアコントロールが有効になったときではなく、メディアコントロールが正しく開始された場合に成功したと見なされます。実行中のメディアコントロールが変更されるか、別のパラメーターまたは NULLを指定してこの関数を再度呼び出すことによって取り消されます。 1 つ以上のパラメーター lpDigitList、 lpMediaList、 lpToneList、および lpCallStateList が NULL の場合、対応する数字、メディアの種類、トーン、または呼び出し状態によってトリガーされるメディアコントロールは無効になります。残りの設定を有効のままにしたままメディアコントロールパラメーターの一部だけを変更するには、アプリケーションで lineSetMediaControl を呼び出し、有効なままにする必要がある部分の前のパラメーターと、変更する部分の新しいパラメーターを指定する必要があります。

hCall が選択され、呼び出しが終了するか、アプリケーションがそのハンドルの割り当てを解除すると、その呼び出しのメディア制御が取り消されます。

呼び出しの所有者であるアプリケーションはすべて、原則として、呼び出しでメディア制御要求を行うことができます。呼び出しを所有するすべてのアプリケーションの呼び出しで未処理にできるのは、1 つのメディア制御要求のみです。 lineSetMediaControl が呼び出されるたびに、新しい要求は、呼び出し元のアプリケーションまたはその他の所有アプリケーションによって設定されたかどうかにかかわらず、呼び出しに有効なメディアコントロールをオーバーライドします。

サービスプロバイダーや、このようなリソースを競合するその他のアクティビティによっては、同時に検出できる数は時間の経過と同時に異なる場合があります。サービスプロバイダーリソースがオーバーコミットされると、LINEERR_RESOURCEUNAVAIL エラーが返されます。

メディア制御がサービスプロバイダーによってサポートされているかどうかは、デバイスの機能です。