TSPI_linePickup関数 (tspi.h)

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

TSPI_linePickup関数は、指定した宛先アドレスで警告する呼び出しを取得し、選択した呼び出しの呼び出しハンドルを返します。 lpszDestAddress パラメーターに対して NULL で呼び出された場合、グループピックアップが実行されます。デバイス機能で必要な場合、 lpszGroupID は、アラートステーションが属するグループ識別子を指定します。

構文

LONG TSPIAPI TSPI_linePickup(
  DRV_REQUESTID dwRequestID,
  HDRVLINE      hdLine,
  DWORD         dwAddressID,
  HTAPICALL     htCall,
  LPHDRVCALL    lphdCall,
  LPCWSTR       lpszDestAddress,
  LPCWSTR       lpszGroupID
);

パラメーター

dwRequestID

非同期要求の識別子。

hdLine

呼び出しを取得する行へのハンドル。

dwAddressID

ピックアップの送信元となる hdLine のアドレス。アドレス識別子は、アドレスに永続的に関連付けられます。識別子はオペレーティングシステムのアップグレード全体で一定のままです。

htCall

新しい呼び出しへの TAPI ハンドル。サービスプロバイダーはこれを保存し、呼び出しのイベントを報告する LINEEVENT プロシージャの後続のすべての呼び出しで使用する必要があります。

lphdCall

呼び出しのサービスプロバイダーの識別子を表す HDRVCALL へのポインター。サービスプロバイダーは、このプロシージャが返される前に、呼び出しのハンドルをこの場所に入力する必要があります。関数でエラーが発生した場合、このハンドルは TAPI によって無視されます。

lpszDestAddress

呼び出しが取得されるアドレスを含む null で終わる Unicode 文字列へのポインター。アドレスは標準のリンク形式です。

lpszGroupID

アラートステーションが属するグループ識別子を含む null で終わる Unicode 文字列へのポインター。このパラメーターは、現在のピックアップグループの外部で呼び出しをピックアップするために、一部のスイッチで必要です。

注lpszGroupID は、lpszDestAddress の NULL ポインターを使用してそれ自体で指定できます。または、 lpszGroupID を lpszDestAddress に加えて指定することもできます (デバイスで必要な場合)。 NULL 自体にすることもできます。

戻り値

dwRequestID を返します。エラーが発生した場合はエラー番号を返します。対応するASYNC_COMPLETIONの lResult 実際のパラメーターは、関数が成功した場合は 0、エラーが発生した場合はエラー番号です。可能な戻り値は次のとおりです。

LINEERR_INVALLINEHANDLE、LINEERR_NOMEM、LINEERR_INVALADDRESSID、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALADDRESS、LINEERR_OPERATIONFAILED、LINEERR_INVALGROUPID、LINEERR_RESOURCEUNAVAIL。

注釈

呼び出しが正常に取得されると、サービスプロバイダーは呼び出し状態の変更に関する LINE_CALLSTATE メッセージを TAPI に通知します。 LINECALLINFO 構造体は、取得された呼び出しに関する情報を提供します。通話の理由が ピックアップとして一覧表示されます。この構造体は、 TSPI_lineGetCallInfoを呼び出すことによって使用できます。

サービスプロバイダーは、TSPI_linePickupを使用してユーザーが呼び出し待機シグナルを誤って検出したが、プロバイダーが検出を実行できない呼び出しを取得できる場合、LINEADDRESSCAPS 構造体でLINEADDRCAPFLAGS_PICKUPCALLWAITを TRUE に設定します。これにより、サービスプロバイダーが呼び出し待機シグナルを検出できなかった場合でも、ユーザーは待機中の呼び出しに応答するメカニズムが提供されます。呼び出し待機呼び出しを取得するために TSPI_linePickup が使用されている場合、 lpszDestAddress と lpszGroupID ポインターパラメーターの両方が NULL になります。サービスプロバイダーは、待機中の呼び出しの新しい呼び出しハンドルを作成し、そのハンドルを lphdCall 内のユーザーに渡します。 dwAddressID パラメーターは、ほとんどの場合 0 です (特に単一行の住宅の場合)。

TSPI_linePickupを使用して 2 番目の呼び出しを取得すると、TSPI_lineSwapHoldを使用してそれらを切り替えることができます。 TSPI_lineDrop を使用して、一方をドロップ (もう一方に切り替える) などを行うことができます。ユーザーが現在の呼び出しを削除して 2 番目の呼び出しを受け取る場合は、呼び出し待機中のビープ音が鳴ったときに TSPI_lineDrop を呼び出し、2 番目の呼び出しが呼び出されるまで待ってから、新しい呼び出しハンドルでTSPI_lineAnswer を呼び出します。サービスプロバイダーは、LINEADDRESSSTATUS の dwAddressFeatures メンバーのLINEADDRFEATURE_PICKUP フラグを設定して、集荷が実際に可能であることを示します。

この関数は、呼び出しの有効期間を開始するために TSPI モデルに従うという点で、対応する TAPI 関数とは異なります。 TAPI とサービスプロバイダーは、呼び出しを表す不透明なハンドルを相互に交換します。さらに、サービスプロバイダーは、このプロシージャから戻る前に、新しい呼び出しのコールバックを実行できます。いずれの場合も、サービスプロバイダーは、一致する ASYNC_COMPLETION メッセージが成功を報告するまで、返されたハンドルを "まだ有効ではありません" として扱う必要があります。つまり、新しい呼び出しに LINEEVENT メッセージを発行したり、その行のメッセージまたは状態データ構造の呼び出し数に含めたりすることはできません。