TSPI_lineGatherDigits関数 (tspi.h)

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

TSPI_lineGatherDigits関数は、指定された呼び出しでバッファーに格納された数字の収集を開始します。 TAPI は、桁数と収集する最大桁数を配置するバッファーを指定します。

構文

LONG TSPIAPI TSPI_lineGatherDigits(
  HDRVCALL hdCall,
  DWORD    dwEndToEndID,
  DWORD    dwDigitModes,
  LPWSTR   lpsDigits,
  DWORD    dwNumDigits,
  LPCWSTR  lpszTerminationDigits,
  DWORD    dwFirstDigitTimeout,
  DWORD    dwInterDigitTimeout
);

パラメーター

hdCall

ディジット収集を実行する呼び出しに対するサービスプロバイダーのハンドル。 hdCall の呼び出し状態は、アイドル状態を除く任意の状態にすることができます。

dwEndToEndID

一致する LINE_GATHERDIGITS メッセージが送信されるまで、その有効期間全体の要求の一意の解釈されていない識別子。サービスプロバイダーは、この識別子をメッセージのパラメーターの 1 つとして含めます。

dwDigitModes

監視するディジットモード。このパラメーターは、次のLINEDIGITMODE_定数の 1 つ以上を使用します。

値	意味
LINEDIGITMODE_PULSE	回転パルスシーケンスの使用の結果である可聴クリックとして数字を検出します。パルスモードの有効な数字は、'0' から '9' です。
LINEDIGITMODE_DTMF	DTMF トーンとしてディジットを検出します。 DTMF モードの有効な数字は、'0' から '9'、'A'、'B'、'C'、'D'、'*'、'#' です。

lpsDigits

検出された数字がテキスト文字として格納されるバッファーへのポインター。サービスプロバイダーは、収集時に一度に 1 桁の数字をバッファーに配置できますが、必須ではありません。 LINE_GATHERDIGITS メッセージが送信されると、バッファーの内容が完了している必要があります。 lpsDigits が NULL として指定されている場合、呼び出しで現在進行中の桁収集は取り消され、dwNumDigits パラメーターは無視されます。それ以外の場合、 lpsDigits には dwNumDigits 数字のスペースがあると見なされます。

dwNumDigits

LINE_GATHERDIGITS メッセージが TAPI に送信される前に収集される桁数。 lpsDigits が NULL の場合、dwNumDigits パラメーターは無視されます。 dwNumDigits が 0 の場合、この関数はLINEERR_INVALPARAMを返す必要があります。

lpszTerminationDigits

テキスト文字としての終了数字の null で終わる Unicode 文字列へのポインター。文字列内のいずれかの数字が検出されると、その終了桁がバッファーに追加され、digit コレクションが終了し、 LINE_GATHERDIGITS メッセージが TAPI に送信されます。

パルスモードの有効な文字は、'0' から '9' です。 DTMF モードの有効な文字は、'0' から '9'、'A'、'B'、'C'、'D'、'*'、'#' です。このポインターが NULL の場合、または空の文字列を指している場合、関数は終了桁が指定されていないかのように動作します。

dwFirstDigitTimeout

最初の桁が予期される時間 (ミリ秒単位)。この時間枠で最初の桁が受信されない場合は、桁の収集が終了し、LINE_GATHERDIGITSメッセージが TAPI に送信されます。 1 つの NULL 文字がバッファーに書き込まれます。これは、数字が受信されておらず、最初の桁のタイムアウトが終了した桁の収集を示します。呼び出しのラインデバイス機能は、このパラメーターの有効な範囲を指定するか、タイムアウトがサポートされていないことを示します。このパラメーターは、この関数が呼び出されたときに TAPI によって検証されません。

dwInterDigitTimeout

連続する数字の間の最大時間 (ミリ秒単位)。この時間枠で桁が受信されない場合は、digit コレクションが終了し、 LINE_GATHERDIGITS メッセージが TAPI に送信されます。 1 つの NULL 文字がバッファーに書き込まれ、インターディジットタイムアウトによって桁収集が終了したことを示します。 LINEDEVCAPS 構造体は、このパラメーターの有効な範囲を指定するか、タイムアウトがサポートされていないことを示す必要があります。このパラメーターは、この関数が呼び出されたときに TAPI によって検証されません。

戻り値

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

LINEERR_INVALCALLHANDLE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALCALLSTATE、LINEERR_NOMEM、LINEERR_INVALTIMEOUT、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALDIGITMODE、LINEERR_OPERATIONFAILED、LINEERR_INVALDIGITS、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPARAM。

注釈

dwNumDigits パラメーターが無効な場合、サービスプロバイダーはLINEERR_INVALPARAMを返します。

桁のコレクションが正しく開始された場合、この関数は 0 (成功) を返します。は、ディジットコレクションが終了した場合はではありません。部分バッファーが返されるすべての場合、有効な数字 (存在する場合) の後に Unicode NULL 文字が続きます。

Digit コレクションは、次の方法で終了できます。

要求された桁数が収集されている可能性があります。
検出された数字の 1 つは、指定した桁数が収集される前の szTerminationDigits の数字と一致します。検出された終了桁もバッファーに配置され、部分バッファーが返されます。
タイムアウトの 1 つが期限切れになります。 dwFirstDigitTimeout は、この期間内に最初の桁が受信されない場合に期限切れになります。 dwInterDigitTimout は、前に検出された数字からその期間内に 2 番目、3 番目、(など) の桁が受信されず、部分的なバッファーが返された場合に期限切れになります。
コレクションの進行中にこの操作を再度呼び出します。古いコレクションセッションが終了し、古いバッファーの内容が未定義です。別の操作を開始せずに桁収集を取り消すために、この操作は NULL と等しい lpsDigits で呼び出されます。

この関数は アイドル状態を除く任意の呼び出し状態で呼び出すことができますが、通常、数字は呼び出しが接続状態の間にのみ収集できます。

通常、LINE_GATHERDIGITS メッセージは、数字バッファーがいっぱいになると送信されます。また、タイムアウトまたは終了桁数の一致のために部分的なバッファーが返された場合、または呼び出しで別の TSPI_lineGatherDigits 要求を介して要求が取り消された場合にも送信されます。一度にアクティブにできる収集桁は 1 桁のみです。サービスプロバイダーは、TSPI_lineGatherDigitsが呼び出されたときに、LINE_GATHERDIGITS メッセージで未処理の収集操作を終了する必要があります。

TSPI_lineGatherDigits関数の呼び出しに関連付けられた操作が取り消されると (関数の後続の呼び出しによって)、サービスプロバイダーは、その時点まで収集されたすべての数字を、元の呼び出しで指定されたバッファーにコピーします。

TAPI では、 TSPI_lineMonitorDigits を使用して、バッファーなしのディジット検出を有効または無効にすることができます。この方法で数字が検出されるたびに、 LINE_MONITORDIGITS メッセージが TAPI に送信されます。同じ呼び出しに対して、バッファー (数字の収集) とバッファーなしのディジット検出の両方を同時に有効にすることができます。

サービスプロバイダーでは、この関数で使用されるタイミングの品質に多少のばらつきが許容されます。これには、タイミングをまったく実行しないことも含まれます。タイミングの品質は、 LINEDEVCAPS のメンバー dwGatherDigitsMinTimeout と dwGatherDigitsMaxTimeout で報告されます。

TAPI レベルの対応する関数には、仮パラメーター dwEndToEndID は含まれません。そのレベルでは、エンドツーエンドのマーキングはありません。 TAPI は、TSPI レベルでエンドツーエンドのマーキングを使用して、 あるTSPI_lineGatherDigits 要求を別の要求と区別します。