TSPI_lineDrop函式 (tspi.h)

發行項
03/03/2024

TSPI_lineDrop函式會卸除或中斷指定的呼叫。用戶可以選擇性地在通話中斷連線期間傳輸用戶資訊。應用程式可以隨時呼叫此函式。當 TSPI_lineDrop 傳回時，呼叫應該閑置。

語法

LONG TSPIAPI TSPI_lineDrop(
  DRV_REQUESTID dwRequestID,
  HDRVCALL      hdCall,
  LPCSTR        lpsUserUserInfo,
  DWORD         dwSize
);

參數

dwRequestID

異步要求的標識碼。

hdCall

要卸除之呼叫的服務提供者句柄。 hdCall 的呼叫狀態可以是閑置以外的任何狀態。

lpsUserUserInfo

只有當 dwSize 不是零時，這個指標才有效。它會指定要在呼叫中斷連線時傳送給遠端合作物件的 Null 終止字串指標，其中包含要傳送給遠端合作對象的用戶資訊。如果未傳送使用者使用者資訊，則此指標為 NULL 。只有在基礎網路支援時，用戶使用者資訊才會傳送 (請參閱 LINEDEVCAPS) 。

dwSize

lpsUserUserInfo 中使用者資訊位元組的大小。如果 lpsUserUserInfo 為 NULL， 則會忽略 dwSize 。

傳回值

如果發生錯誤，則傳回 dwRequestID 或錯誤號碼。如果函式成功，則對應ASYNC_COMPLETION的 lResult 實際參數為零;如果發生錯誤，則為錯誤號碼。可能的傳回值如下所示：

LINEERR_INVALCALLHANDLE、LINEERR_OPERATIONFAILED、LINEERR_INVALCALLSTATE、LINEERR_RESOURCEUNAVAIL、LINEERR_NOMEM、LINEERR_USERUSERINFOTOOBIG、LINEERR_OPERATIONUNAVAIL。

備註

如果呼叫的目前狀態不允許卸除呼叫，服務提供者會傳回LINEERR_INVALCALLSTATE。

叫 用TSPI_lineDrop時，相關的呼叫有時也會受到影響。例如，卸除會議通話可能會卸除所有參與的個別通話。 LINE_CALLSTATE 訊息會針對所有呼叫狀態受到影響的呼叫傳送至TAPI。一般而言，已卸除的呼叫會轉換為閑置狀態。在供應項目狀態的呼叫上叫用TSPI_lineDrop會拒絕呼叫。並非所有電話網路都提供這項功能。

在撥打電話或會議通話建立期間所建立的通話是已卸除的諮詢通話，則處於 OnHoldPending 狀態的原始通話會重新連線，而且通常會重新進入 已連線 的通話狀態。

TAPI 可以選擇在卸除時傳送用戶用戶資訊。即使可以傳送使用者使用者資訊，也不保證網路會將此資訊傳遞給遠端合作物件。

注意當多方在通話時，在各種橋接或合作物件行設定中， TSPI_lineDrop 可能無法實際清除呼叫。