lineGenerateTone 関数 (tapi.h)

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

lineGenerateTone 関数は、指定された呼び出しに対して指定されたインバンドトーンを生成します。 dwToneMode に対して 0 を指定してこの関数を呼び出すと、指定された呼び出しで現在進行中のトーン生成が中止されます。トーン生成の進行中に lineGenerateTone または lineGenerateDigits を呼び出すと、現在のトーン生成またはディジット生成が中止され、新しく指定されたトーンまたは数字の生成が開始されます。

構文

LONG lineGenerateTone(
  HCALL                    hCall,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

パラメーター

hCall

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

dwToneMode

生成するトーンを定義します。トーンは標準でもカスタムでもかまいません。カスタムトーンは、任意の周波数のセットで構成されます。少数の標準トーンが事前に定義されています。トーンの継続時間は、標準トーンとカスタムトーンの両方に 対して dwDuration で指定されます。 dwToneMode パラメーターに設定できるビットは 1 つだけです。ビットが設定されていない場合 (値 0 が渡されます)、トーン生成は取り消されます。このパラメーターでは、 LINETONEMODE_定数のいずれかを使用します。

dwDuration

トーンを維持する必要がある期間 (ミリ秒単位)。 dwDuration の値 0 は、指定されたトーンに既定の期間を使用します。既定値は次のとおりです。

カスタム: トーンは、通常はユーザーの操作または機器のタイムアウトによって、シャットダウンされるまで持続されます。

RINGBACK: トーンは、通常、ユーザーの操作または機器のタイムアウトによって、シャットダウンされるまで持続されます。

ビジー:トーンは、通常はユーザーの操作または機器のタイムアウトによって、シャットダウンされるまで持続されます。

BEEP: トーンは、通常、ユーザーの操作または機器のタイムアウトによって、シャットダウンされるまで持続されます。

課金: 固定 (単一サイクル)。

dwNumTones

lpTones 配列内のエントリの数。 dwToneMode が CUSTOM と等しくない場合、このパラメーターは無視されます。

lpTones

トーンのコンポーネントを指定する LINEGENERATETONE 配列へのポインター。このパラメーターは、LINETONEMODE_BUSYなどの標準 LINETONEMODE_定数のトーンでは無視されます。 lpTones がマルチ周波数トーンの場合、さまざまなトーンが同時に再生されます。

戻り値

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

LINEERR_INVALCALLHANDLE、LINEERR_NOTOWNER、LINEERR_INVALCALLSTATE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALPOINTER、LINEERR_OPERATIONFAILED、LINEERR_INVALTONEMODE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALTONE、LINEERR_UNINITIALIZED、LINEERR_NOMEM。

注釈

lineGenerateTone 関数は、トーンの生成が正常に開始されたときに正常に完了したと見なされます。トーンの生成が完了した場合ではありません。この関数を使用すると、リングバック、ビジートーン、ビープ音など、いくつかの定義済みのトーンのインバンド生成が可能になります。また、コンポーネントの周波数、周期、音量を指定することで、カスタムトーンを作成することもできます。これらのトーンはインバンドトーンとして生成されるため、通常、トーン生成を有効にするには接続状態にする必要があります。トーンの生成が完了したとき、またはトーン生成が取り消されると、LINE_GENERATE メッセージがアプリケーションに送信されます。

呼び出しの所有者であるすべてのアプリケーションで、呼び出しごとに進行中のインバンド生成要求 (トーン生成またはディジット生成) は 1 つだけです。これは、呼び出しでトーン生成が現在進行中の場合、 lineGenerateDigits を呼び出すとトーン生成が取り消されることを意味します。

LINEERR_INVALPOINTERエラー値が返された場合、指定された lpTones パラメーターが無効であるか、 dwNumTones パラメーターで指定された値が大きすぎます。