lineForward 関数 (tapi.h)

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

lineForward 関数は、指定した転送命令に従って、指定した行の指定したアドレス宛ての呼び出しを転送します。発信元アドレス (dwAddressID) が転送されると、そのアドレスに対して指定された着信呼び出しは、スイッチによって他の番号に偏向されます。この関数は、前方および応答不可の機能の組み合わせを提供します。この関数は、現在有効になっている転送を取り消すこともできます。

構文

LONG lineForward(
  HLINE                   hLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  LPHCALL                 lphConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

パラメーター

hLine

ラインデバイスへのハンドル。

bAllAddresses

行のすべての発信元アドレスを転送するか、指定されたアドレスだけを転送するかを指定します。 TRUE の場合、行のすべてのアドレスが転送され、dwAddressID は無視されます。FALSE の場合は、dwAddressID として指定されたアドレスのみが転送されます。

dwAddressID

着信呼び出しを転送する指定した行のアドレス。 bAllAddresses が TRUE の場合、このパラメーターは無視されます。

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

lpForwardList

LINEFORWARDLIST 型の特定の転送命令を記述する可変サイズのデータ構造へのポインター。

dwNumRingsNoAnswer

呼び出し前のリングの数は、"応答なし" と見なされます。 dwNumRingsNoAnswer が範囲外の場合、実際の値は許容範囲内で最も近い値に設定されます。

lphConsultCall

HCALL の場所へのポインター。一部のテレフォニー環境では、転送先のパーティに相談するために使用されるコンサルテーション呼び出しへのハンドルがこの場所に読み込まれ、アプリケーションがこの呼び出しの最初の唯一の所有者になります。このポインターは、着信転送にコンサルテーション呼び出しが必要ない環境でも有効である必要があります。コンサルテーション呼び出しが作成されない場合、このハンドルは NULL に 設定されます。

lpCallParams

LINECALLPARAMS 型の構造体へのポインター。 lineForward が転送先への呼び出しを確立する必要がない限り、このポインターは無視されます (lphConsultCall が返されます。この場合、lpCallParams は省略可能です)。 NULL の場合、既定の呼び出しパラメーターが使用されます。それ以外の場合は、指定された呼び出しパラメーターが hConsultCall を確立するために使用されます。

戻り値

関数が非同期的に完了した場合は正の要求識別子を返し、エラーが発生した場合は負のエラー番号を返します。関数が成功した場合は、対応するLINE_REPLY メッセージの dwParam2 パラメーターは 0、エラーが発生した場合は負のエラー番号です。可能な戻り値は次のとおりです。

LINEERR_INVALLINEHANDLE、LINEERR_NOMEM、LINEERR_INVALADDRESSID、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALADDRESS、LINEERR_OPERATIONFAILED、LINEERR_INVALCOUNTRYCODE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPOINTER、LINEERR_STRUCTURETOOSMALL、LINEERR_INVALPARAM、LINEERR_UNINITIALIZED。

注釈

転送が成功した場合は、要求がサービスプロバイダーによって受け入れられただけで、転送はスイッチで設定されていないことを示します。 LINE_ADDRESSSTATE (転送) メッセージは、スイッチで設定された転送の確認を提供します。

アドレスの転送は、この関数が再度呼び出されるまで有効です。最新の転送リストは、古いものを置き換えます。転送は、 null ポインターを lpForwardList として指定することで取り消すことができます。転送リスト内のエントリに NULL 宛先アドレスが指定されている場合、操作は応答不可として機能します。

アドレスの転送状態も外部から影響を受ける可能性があります。たとえば、スイッチでの管理アクションや、別のステーションからのユーザーによるなどです。サービスプロバイダーがこの状態の変化を認識できない場合があり、スイッチに認識されている転送状態との同期を維持できない場合があります。

サービスプロバイダーはアドレスの転送状態を "確実に" 把握していない可能性があるため (つまり、不明な方法で転送または転送されていない可能性があります)、 lineForward は新しい転送手順の設定に失敗しない限り成功します。つまり、転送が有効でないことを一度にすべての転送を取り消す要求は成功します。これは、"未転送" がないためです。変更できるのは、前の転送手順のセットのみです。

この操作の成功または失敗は、前の転送命令のセットに依存せず、異なる転送命令を設定する場合も同じことが当てはまります。プロバイダーは、新しい転送手順を設定する前に、"すべての転送を取り消す" 必要があります。アナログテレフォニー環境では時間がかかる可能性があるため、プロバイダーは現在の転送と新しい転送を比較し、最終的な状態に到達するための指示のみをスイッチに発行する必要があります (転送は変更されません)。

LINEFORWARDLIST に dwNumEntries が 0 に設定されている場合に lineForward を呼び出すと、NULLlpForwardList パラメーターを指定する場合と同じ効果があります。現在有効になっているすべての転送が取り消されます。