lineGatherDigits 関数 (tapi.h)
lineGatherDigits 関数は、指定された呼び出しでバッファーに格納された数字の収集を開始します。 アプリケーションは、収集する桁数と最大桁数を配置するバッファーを指定します。
構文
LONG lineGatherDigits(
HCALL hCall,
DWORD dwDigitModes,
LPSTR lpsDigits,
DWORD dwNumDigits,
LPCSTR lpszTerminationDigits,
DWORD dwFirstDigitTimeout,
DWORD dwInterDigitTimeout
);
パラメーター
hCall
数字を収集する呼び出しを処理します。 アプリケーションは、呼び出しの所有者である必要があります。 hCall の呼び出し状態には、任意の状態を指定できます。
dwDigitModes
監視対象の数字モード。 このパラメーターは、1 つ以上の LINEDIGITMODE_定数を使用します。
lpsDigits
検出された数字がテキスト文字として格納されるバッファーへのポインター。 数字は収集されるため、一度に 1 つずつバッファーに表示されない場合があります。 バッファーの内容が有効であると見なされるのは、 LINE_GATHERDIGITS メッセージを受信した後だけです。 lpsDigits が NULL の場合、呼び出しで現在進行中の桁収集は終了し、dwNumDigits は無視されます。 それ以外の場合、 lpsDigits には dwNumDigits 数字の空きがあると見なされます。
dwNumDigits
LINE_GATHERDIGITS メッセージがアプリケーションに送信される前に収集される桁数。 lpsDigits が NULL の場合、dwNumDigits パラメーターは無視されます。 dwNumDigits が 0 の場合、この関数は失敗します。
lpszTerminationDigits
テキスト文字としての終端の数字の Null で終わる文字列。 文字列内のいずれかの数字が検出されると、その終了桁がバッファーに追加され、digit コレクションが終了し、 LINE_GATHERDIGITS メッセージがアプリケーションに送信されます。
有効な文字の一覧は、 dwDigitModes で指定された定数に依存します。 使用可能な各モードの有効な文字の一覧については、「 定数のLINEDIGITMODE_」を参照してください。
このポインターが NULL の場合、または空の文字列を指している場合、関数は終了桁が指定されていないかのように動作します。
dwFirstDigitTimeout
最初の数字が予想される時間 (ミリ秒単位)。 この時間枠で最初の桁が受信されない場合は、桁の収集が中止され、 LINE_GATHERDIGITS メッセージがアプリケーションに送信されます。 バッファーには NULL 文字のみが含まれています。これは、数字が受信されなかったことを示し、最初の桁タイムアウトで桁収集が終了したことを示します。 呼び出しのラインデバイス機能は、このパラメーターの有効な範囲を指定するか、タイムアウトがサポートされていないことを示します。
dwInterDigitTimeout
連続する数字の間の最大時間 (ミリ秒単位)。 この時間枠内に数字が受信されない場合、桁の収集は中止され、LINE_GATHERDIGITSメッセージがアプリケーションに送信されます。 バッファーには、この時点まで収集された数字の後に NULL 文字のみが含まれています。これは、ディジット間タイムアウトによって桁収集が終了したことを示します。 呼び出しのラインデバイス機能は、このパラメーターの有効な範囲を指定するか、タイムアウトがサポートされていないことを示します。
戻り値
要求が成功した場合は 0 を返し、エラーが発生した場合は負のエラー番号を返します。 可能な戻り値は次のとおりです。
LINEERR_INVALCALLHANDLE、LINEERR_NOMEM、LINEERR_INVALCALLSTATE、LINEERR_NOTOWNER、LINEERR_INVALDIGITMODE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALDIGITS、LINEERR_OPERATIONFAILED、LINEERR_INVALPARAM、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPOINTER、LINEERR_UNINITIALIZED。
解説
Digit コレクションは、要求された桁数が収集されると終了します。 また、指定された桁数が収集される前に、検出された数字の 1 つが szTerminationDigits の数字と一致した場合にも終了します。 検出された終了桁もバッファーに配置され、部分バッファーが返されます。
ディジット コレクションを取り消すもう 1 つの方法は、タイムアウトの 1 つが期限切れになったときに発生します。 dwFirstDigitTimeout は、この期間内に最初の桁が受信されない場合に期限切れになります。 dwInterDigitTimout は、前に検出された数字からその期間内に 2 番目、3 番目、(など) の数字が受信されず、部分的なバッファーが返された場合に期限切れになります。
ディジット コレクションを終了する 4 番目のメソッドは、コレクションの進行中にこの関数を再度呼び出すことです。 古いコレクション セッションが終了し、その時点まで収集されたすべての数字がこの関数の前の呼び出しから提供されたバッファーにコピーされ、 LINE_GATHERDIGITS メッセージがアプリケーションに送信されるときにバッファーが配信されます。 数字の別の収集を開始せずに桁収集を終了するメカニズムは、 lpsDigits が NULL に等しい場合にこの関数を呼び出す方法です。
この関数は、数字コレクションが正しく開始された場合は成功したと見なされ、桁コレクションが終了した場合は成功と見なされません。 部分バッファーが返されるすべての場合、有効な数字 (ある場合) の後に NULL 文字が続きます。
この関数は任意の呼び出し状態で呼び出すことができますが、通常、数字は呼び出しが 接続 状態の間にのみ収集できます。
メッセージ LINE_GATHERDIGITSは、要求を開始したアプリケーションにのみ送信されます。 また、タイムアウトまたは一致する終了桁数のために部分バッファーが返された場合、または呼び出しで別の lineGatherDigits 要求によって要求が取り消された場合にも送信されます。 呼び出しの所有者であるすべてのアプリケーションで、いつでも 1 つの gather-digits 要求のみを呼び出しでアクティブにすることができます。 操作の非同期動作を考えると、複数の lineGatherDigits 要求を連続して発行するアプリケーションで、これを行い、後で複数のLINE_GATHERDIGITS メッセージを受信できる場合があります。 これは通常とは異なるアプリケーションの動作ですが、アプリケーションはこれらのメッセージの数をカウントして、キャンセル メッセージを以前の要求と一致させることができます。 いずれの場合も、最新の要求のみが有効であると見なす必要があります。
電話会議での数字の収集は hConfCall にのみ適用され、参加している個々の通話には適用されません。
lineGatherDigits 関数を使用して前の要求を取り消して数字を収集する場合、この関数は、その時点まで収集された任意の数字を、元の関数呼び出しで指定されたバッファーにコピーします。 その後、関数は、2 番目の呼び出しの lpszDigits パラメーターが NULL アドレスまたは異なるアドレスを指定しているかどうかに関係なく、LINE_GATHERDIGITS メッセージをアプリケーションに送信します。
必要条件
| 対象プラットフォーム | Windows |
| ヘッダー | tapi.h |
| Library | Tapi32.lib |
| [DLL] | Tapi32.dll |