TSPI_lineForward関数 (tspi.h)
TSPI_lineForward関数は、指定した転送手順に従って、指定した行の指定したアドレス宛ての呼び出しを転送します。 発信元アドレス (dwAddressID) が転送されると、そのアドレスに対して指定された着信呼び出しは、スイッチによって他の番号に偏向されます。 この関数は、転送機能と応答不可機能の組み合わせを提供します。 この関数は、現在有効になっている特定の転送を取り消すこともできます。
構文
LONG TSPIAPI TSPI_lineForward(
DRV_REQUESTID dwRequestID,
HDRVLINE hdLine,
DWORD bAllAddresses,
DWORD dwAddressID,
LPLINEFORWARDLIST const lpForwardList,
DWORD dwNumRingsNoAnswer,
HTAPICALL htConsultCall,
LPHDRVCALL lphdConsultCall,
LPLINECALLPARAMS const lpCallParams
);
パラメーター
dwRequestID
非同期要求の識別子。
hdLine
転送される行へのサービス プロバイダーのハンドル。
bAllAddresses
行のすべての発信元アドレスを転送するか、指定したアドレスのみを転送するかを指定します。 TRUE の場合、行のすべてのアドレスが転送され、 dwAddressID は無視されます。 FALSE の場合、 dwAddressID として指定されたアドレスのみが転送されます。 このパラメーターは、この関数が呼び出されたときに TAPI によって検証されません。
dwAddressID
着信呼び出しを転送する指定した行のアドレス。 bAllAddresses が TRUE の場合、このパラメーターは無視されます。 このパラメーターは、この関数が呼び出されたときに TAPI によって検証されません。
アドレス識別子は、アドレスに永続的に関連付けられます。識別子はオペレーティング システムのアップグレード全体で一定のままです。
lpForwardList
特定の転送命令を記述する LINEFORWARDLIST 型の可変サイズのデータ構造へのポインター。
dwNumRingsNoAnswer
着信呼び出しが "応答なし" と見なされる前のリングの数を指定します。 dwNumRingsNoAnswer が範囲外の場合、実際の値は許容範囲の最も近い値に設定されます。 このパラメーターは、この関数が呼び出されたときに TAPI によって検証されません。
htConsultCall
サービス プロバイダーがこのような呼び出しを作成する必要がある場合は、TAPI ハンドルを新しい呼び出しに処理します。 一部のテレフォニー環境では、通話を転送すると、転送先のパーティに相談するために使用されるコンサルテーションコールを作成する副作用があります。 このような環境では、サービス プロバイダーは新しいコンサルテーション呼び出しを作成し、この値を保存し、呼び出しのイベントを報告する LINEEVENT プロシージャへの後続のすべての呼び出しで使用する必要があります。 コンサルテーション呼び出しが作成されない場合、この値はサービス プロバイダーによって無視できます。
lphdConsultCall
呼び出しのサービス プロバイダーの識別子を表す HDRVCALL へのポインター。 通話の転送が、転送先のパーティに問い合わせて使用されるコンサルテーション呼び出しを作成する副作用があるテレフォニー環境では、サービス プロバイダーは、このプロシージャが返される前に、この場所に呼び出しのハンドルを入力する必要があります。 サービス プロバイダーは、このプロシージャから戻る前に、新しい呼び出しに関するコールバックを実行できます。 コンサルテーション呼び出しが作成されない場合は、HDRVCALL を NULL のままにする必要があります。
lpCallParams
LINECALLPARAMS 型の構造体へのポインター。 lineForward が転送先への呼び出しの確立を要求しない限り、このポインターはサービス プロバイダーによって無視されます (lphdConsultCall が返されます。この場合、lpCallParams は省略可能です)。 NULL の場合、既定の呼び出しパラメーターが使用されます。 それ以外の場合は、 htConsultCall を確立するために指定された呼び出しパラメーターが使用されます。
戻り値
エラーが発生した場合は 、dwRequestID またはエラー番号を返します。 対応するASYNC_COMPLETIONの lResult 実際のパラメーターは、関数が成功した場合は 0、エラーが発生した場合はエラー番号です。 可能な戻り値は次のとおりです。
LINEERR_INVALLINEHANDLE、LINEERR_NOMEM、LINEERR_INVALADDRESS、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALADDRESSID、LINEERR_OPERATIONFAILED、LINEERR_INVALCOUNTRYCODE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPARAM、LINEERR_STRUCTURETOOSMALL。
注釈
指定した転送リスト パラメーターに無効な情報が含まれている場合、サービス プロバイダーはLINEERR_INVALPARAMを返します。
サービス プロバイダーは、LINEERR_INVALADDRESSを返す場合、ダイヤルを実行しません。
サービス プロバイダーは、この関数に成功を返して、要求がサービス プロバイダーによって受け入れられることを示すだけで、転送がスイッチで設定されていないことを示します。 LINE_ADDRESSSTATE (転送 ) メッセージが送信され、スイッチで転送が設定されます。
アドレスまたはアドレスの転送は、この関数が再度呼び出されるまで有効です。 最新の転送リストは、有効な古いものを置き換えます。 この関数が呼び出され、 NULL ポインターが lpForwardList として指定されている場合、サービス プロバイダーは、その時点で実行されている転送をすべて取り消す必要があります。 転送リストのエントリに NULL 宛先アドレスが指定されている場合、操作は "応答不可" として機能します。
アドレスの転送状態は、スイッチの管理アクションや別のステーションからのユーザーなどによって、外部から影響を受ける場合もあります。 サービス プロバイダーがこの状態の変化を認識できない可能性があり、スイッチに認識されている転送状態と同期を維持できない場合があります。 プロバイダーは常に true であることがわかっていることを示し、それ以外の場合は転送状態が不明であることを示す必要があります。
サービス プロバイダーは間違いなくアドレスの転送状態を知らない可能性があるため (つまり、不明な方法で転送または転送されていない可能性があります)、新しい転送手順の設定に失敗しない限り 、TSPI_lineForward は成功します。 つまり、転送が有効でないときにすべての転送を取り消す要求が成功します。 これは、不向きがないためです。新しい転送手順のセットのみを呼び出すことができます。
この操作の成功または失敗は、前の転送命令セットに依存せず、異なる転送命令を設定する場合も同じです。 必要に応じて、新しい転送手順を設定する前に、プロバイダーが "すべての転送を未適用" にする必要があります。 アナログ テレフォニー環境では時間がかかる場合があるため、プロバイダーは現在の転送と新しい転送を比較し、最終的な状態に到達するための指示のみをスイッチに発行する必要があります (変更されていない転送は影響を受けません)。
LINEFORWARDLIST で dwNumEntries が 0 に設定されている場合にTSPI_lineForwardを呼び出すと、NULLlpForwardList パラメーターを指定した場合と同じ効果があります。現在有効になっているすべての転送が取り消されます。
LPhdConsultCall に返される NULL 値は、サービス プロバイダーがコンサルテーション呼び出しを作成したかどうかを TAPI が判断する唯一の方法であるため、サービス プロバイダーは呼び出しハンドルとして NULL を使用できません。
この関数は、呼び出しの有効期間を開始するために TSPI モデルに従うという点で、対応する TAPI 関数とは異なります。 TAPI とサービス プロバイダーは、呼び出しを表す不透明なハンドルを相互に交換します。 さらに、サービス プロバイダーは、このプロシージャから戻る前に、新しい呼び出しのコールバックを実行できます。 いずれの場合も、サービス プロバイダーは、一致する ASYNC_COMPLETION が成功を報告するまで、返されたハンドルを "まだ有効ではありません" として扱う必要があります。 つまり、新しい呼び出しのメッセージを発行したり、行のメッセージまたは状態データ構造の呼び出し数に含めたりすることはできません。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | Windows |
| ヘッダー | tspi.h |