TSPI_linePickup函式 (tspi.h)

發行項
03/09/2024

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 指標來指定。或者，如果裝置需要，除了 lpszDestAddress 之外，還可以指定 lpszGroupID。它也可以是 NULL 本身。

傳回值

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

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

備註

成功接聽通話時，服務提供者會向 TAPI 發出有關通話狀態變更的LINE_CALLSTATE 訊息。 LINECALLINFO 結構提供已挑選之呼叫的相關信息。它會列出呼叫為取貨的原因。呼叫 TSPI_lineGetCallInfo即可使用此結構。

如果TSPI_linePickup可用來挑選使用者偵測到呼叫等候訊號的呼叫，則服務提供者會將LINEADDRESSCAPS結構中的LINEADDRCAPFLAGS_PICKUPCALLWAIT設定為TRUE，但提供者無法執行偵測。這可讓使用者有一種回應等候呼叫的機制，即使服務提供者無法偵測到呼叫等候訊號也一樣。當 TSPI_linePickup 用來挑選呼叫等候呼叫時， lpszDestAddress 和 lpszGroupID 指標參數都是 NULL。服務提供者會建立等候呼叫的新呼叫句柄，並將該句柄傳遞給 lphdCall 中的使用者。 dwAddressID 參數通常是零 (，特別是在單行房屋案例中) 。

一旦 TSPI_linePickup 用來接聽第二次呼叫， TSPI_lineSwapHold 可用來在兩者之間切換。 TSPI_lineDrop 可用來卸除一個 (，並切換至另一個) 等等。如果使用者想要卸除目前的通話並接聽第二個通話，他們會在收到呼叫等候的電話時呼叫 TSPI_lineDrop ，等候第二次呼叫來電來電，然後在新的呼叫句柄上呼叫 TSPI_lineAnswer 。服務提供者會在 LINEADDRESSSTATUS 的 dwAddressFeatures 成員中設定LINEADDRFEATURE_PICKUP旗標，以指出實際可能取貨時間。

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