TSPI_lineSetupConference函式 (tspi.h)

發行項
03/03/2024

TSPI_lineSetupConference函式會為第三方新增設定通話。

語法

LONG TSPIAPI TSPI_lineSetupConference(
  DRV_REQUESTID          dwRequestID,
  HDRVCALL               hdCall,
  HDRVLINE               hdLine,
  HTAPICALL              htConfCall,
  LPHDRVCALL             lphdConfCall,
  HTAPICALL              htConsultCall,
  LPHDRVCALL             lphdConsultCall,
  DWORD                  dwNumParties,
  LPLINECALLPARAMS const lpCallParams
);

參數

dwRequestID

異步要求的標識碼。

hdCall

識別會議第一方之初始通話的句柄。在某些環境中，通話必須存在，才能開始通話。在其他電話語音環境中，一開始沒有任何通話存在， 且 hdCall 會保留 NULL。 hdCall 的呼叫狀態可以連線。

hdLine

如果 hdCall 為 NULL，則為產生會議通話之線路裝置的句柄。如果 hdCall 為非 NULL，則會忽略 hdLine 參數。服務提供者會透過LINEADDRESSCAPS數據結構的 setupConfNull 旗標報告其支援模型。

htConfCall

新通話的 TAPI 句柄。服務提供者必須儲存此專案，並將其用於新呼叫上報告事件的所有後續 LINEEVENT 程式呼叫中。

lphdConfCall

HDRVCALL 的指標，代表新建立之電話的服務提供者標識碼。服務提供者必須在這個程式傳回之前，將此位置填入新呼叫的句柄。如果函式產生錯誤，TAPI 會忽略此句柄。 hdConfCall 的呼叫狀態不適用。

htConsultCall

對諮詢通話的 TAPI 句柄。為新增新的合作物件設定通話時，會自動配置新的暫時通話 (諮詢通話) 。服務提供者必須儲存 htConsultCall ，並在新的諮詢呼叫上報告事件的所有後續 LINEEVENT 程式呼叫中使用它。

lphdConsultCall

HDRVCALL 的指標，代表呼叫的服務提供者標識符。為新增新的合作物件設定通話時，會自動配置新的暫時通話 (諮詢通話) 。服務提供者必須在這個程式傳回之前，填入這個位置的新諮詢呼叫句柄。如果函式產生錯誤，TAPI 會忽略此句柄。 hdConsultCall 的呼叫狀態不適用。

dwNumParties

會議中的預期合作物件數目。服務提供者可以隨意使用此號碼。例如，服務提供者可以忽略它，或使用它做為提示，在交換器內配置正確的大小會議網橋。呼叫此函式時，TAPI 不會驗證此參數。

lpCallParams

LINECALLPARAMS 結構的指標，包含建立諮詢通話時要使用的呼叫參數。如果不需要特殊呼叫安裝參數，且服務提供者使用預設參數，此參數會設定為 NULL 。

傳回值

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

LINEERR_INVALCALLHANDLE、LINEERR_INVALADDRESSMODE、LINEERR_INVALLINEHANDLE、LINEERR_INVALBEARERMODE、LINEERR_INVALCALLSTATE、LINEERR_INVALCALLPARAMS、LINEERR_CALLUNAVAIL、LINEERR_INVALLINESTATE、LINEERR_CONFERENCEFULL、LINEERR_INVALMEDIAMODE、LINEERR_NOMEM、LINEERR_INVALRATE、LINEERR_OPERATIONUNAVAIL、LINEERR_INUSE、LINEERR_OPERATIONFAILED、LINEERR_RATEUNAVAIL、LINEERR_RESOURCEUNAVAIL、LINEERR_USERUSERINFOTOOBIG LINEERR_BEARERMODEUNAVAIL。

備註

如果包含電話會議之行的指定行句柄無效，則服務提供者會傳回LINEERR_INVALLINEHANDLE。此錯誤也可以指出電話語音環境需要初始線路才能設定會議，但已改為提供非 NULL 通話句柄。

如果電話語音環境需要初始通話才能設定會議，但已改為提供 NULL 通話句柄，則服務提供者會傳回LINEERR_INVALCALLHANDLE。

TSPI_lineSetupConference 提供兩種方式來建立新的通話，視是否需要一般兩方通話才能預先存在而定。從現有的兩方通話設定電話時， hdCall 參數是有效的通話句柄，一開始會由 TSPI_lineSetupConference 要求新增至會議通話，並忽略 hdLine 。在電話設定不是以現有通話開頭的交換器上， hdCall 必須是 NULL ，而且必須指定 hdLine ，才能識別要起始通話的線路裝置。不論是哪一種情況，都會配置諮詢通話，以連線到要新增至通話的合作物件。 TAPI 可以使用 TSPI_lineDial 來撥打另一方的位址。

會議通話通常會轉換成 onHoldPendingConference 狀態、諮詢通話撥號狀態，以及如果一) 進入會議狀態，則初始通話 (。

您也可以使用解析為三向會議的 TSPI_lineCompleteTransfer 函式來設定會議。

TAPI 可以使用 TSPI_lineSwapHold，在諮詢通話與會議通話之間切換。

TSPI_lineUnhold函式可以復原呼叫狀態為 onHoldPendingConference 的呼叫。如果這樣做，任何諮詢通話通常會進入閑置狀態。

您可以叫用 TSPI_lineDrop來取消諮詢通話。卸除諮詢通話時，現有的會議通話通常會轉換回聯機狀態。 TAPI 及其用戶端應用程式應該觀察 LINE_CALLSTATE 訊息，以確切判斷呼叫會發生什麼情況。例如，如果會議通話還原回一般兩方通話，會議通話就會 變成閑置 狀態，而原始參與者通話可能會還原為 已連線。

此函式與對應的 TAPI 函式不同，因為它會遵循 TSPI 模型，以開始呼叫的存留期。 TAPI 和服務提供者交換不透明的句柄，代表彼此的呼叫。此外，服務提供者可以在從這個程式傳回之前，先執行新呼叫的回呼。在任何情況下，服務提供者也必須將傳回的句柄視為「無效」，直到比對 ASYNC_COMPLETION 訊息回報成功為止。換句話說，它不得針對新呼叫發出任何 LINEEVENT 訊息，或將它包含在該行的訊息或狀態數據結構中的呼叫計數中。