TSPI_lineForward函式 (tspi.h)

發行項
03/09/2024

TSPI_lineForward函式會根據指定的轉送指示，轉送指定之行上指定位址的呼叫。當原始位址 (dwAddressID) 轉送時，該位址的指定連入呼叫會由參數反轉為其他號碼。此函式提供向前和不打擾功能的組合。此函式也可以取消目前作用中的特定轉送。

語法

LONG TSPIAPI TSPI_lineForward(
  DRV_REQUESTID           dwRequestID,
  HDRVLINE                hdLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  HTAPICALL               htConsultCall,
  LPHDRVCALL              lphdConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

參數

dwRequestID

異步要求的標識碼。

hdLine

要轉送之行的服務提供者句柄。

bAllAddresses

指定行上的所有原始位址，還是只指定要轉送的位址。如果為 TRUE，則會轉送行上的所有位址，並忽略 dwAddressID ;如果 為 FALSE，則只會轉送指定為 dwAddressID 的 位址。呼叫此函式時，TAPI 不會驗證此參數。

dwAddressID

要轉送來電的指定行位址。如果 bAllAddresses 為 TRUE，則會忽略此參數。呼叫此函式時，TAPI 不會驗證此參數。

位址標識符永久與地址相關聯;標識碼在操作系統升級之間維持不變。

lpForwardList

LINEFORWARDLIST 類型的可變大小數據結構的指標，描述特定的轉送指示。

dwNumRingsNoAnswer

指定傳入通話視為「沒有答案」之前的通道數目。如果 dwNumRingsNoAnswer 超出範圍，則實際值會設定為允許範圍內最接近的值。呼叫此函式時，TAPI 不會驗證此參數。

htConsultCall

如果服務提供者必須建立這類呼叫，則TAPI會處理新的呼叫。在某些電話語音環境中，轉接通話會產生建立諮詢通話的副作用，用來諮詢轉接的合作物件。在這類環境中，服務提供者會建立新的諮詢呼叫，而且必須儲存此值，並在呼叫上的 LINEEVENT 程式報告事件的所有後續呼叫中使用它。如果未建立諮詢呼叫，服務提供者可以忽略此值。

lphdConsultCall

HDRVCALL 的指標，代表呼叫的服務提供者標識符。在轉接通話的電話語音環境中，建立用來諮詢轉接之合作對象的諮詢通話，服務提供者必須在此程式傳回之前，填入此位置的呼叫句柄。服務提供者可以在從這個程式傳回之前，先對新呼叫執行回呼。如果未建立諮詢呼叫，HDRVCALL 必須保留 NULL。

lpCallParams

LINECALLPARAMS 類型的結構的指標。除非 lineForward 需要建立轉送目的地 (的呼叫，而且會傳回 lphdConsultCall ，在此情況下 ，lpCallParams 是選擇性) ，否則服務提供者會忽略此指標。如果 為 NULL，則會使用預設呼叫參數。否則，會使用指定的呼叫參數來建立 htConsultCall。

傳回值

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

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

備註

如果指定的轉寄清單參數包含無效的信息，服務提供者會傳回LINEERR_INVALPARAM。

如果服務提供者傳回LINEERR_INVALADDRESS，則不會執行撥號。

服務提供者會將成功傳回給此函式，只表示服務提供者接受要求，而不是在交換器上設定轉送。傳送 LINE_ADDRESSSTATE (轉送) 訊息，以提供在交換器上設定轉送。

位址或地址的轉送仍有效，直到再次呼叫此函式為止。最新的轉送清單會取代任何作用中的舊轉送清單。如果呼叫此函式，將 NULL 指標指定為 lpForwardList，服務提供者應該取消在該時間執行的任何轉送。如果為轉送清單中的專案指定 NULL 目的地位址，則作業會做為「不干擾」。

位址的轉送狀態也可能受到外部影響，例如，透過交換器上的系統管理動作，或由另一個月臺的用戶影響。服務提供者可能無法察覺此狀態變更，而且可能無法與交換器已知的轉送狀態保持同步。提供者必須一律指出其知道為 true 的內容，並指出轉送狀態為未知，否則為未知。

因為服務提供者可能不知道位址的轉送狀態，但不確定 (也就是說，可能已以未知) 的方式轉送或取消轉寄，除非無法設定新的轉送指示， 否則TSPI_lineForward 成功。換句話說，當沒有轉送成功時，一次取消所有轉送的要求。這是因為沒有未預期的;您只能叫用一組新的轉送指示。

這項作業的成功或失敗不取決於先前的轉送指令集，而設定不同的轉送指令時則相同。如有必要，提供者應該在設定新的轉送指示之前「取消所有專案」。由於這可能需要時間在模擬電話語音環境中，因此提供者可能也會想要比較目前的轉送與新的轉送，而且只會發出切換的指示，以進入最終狀態， (維持未變更的轉寄) 。

當 LINEFORWARDLIST 設定為零的 dwNumEntries 時叫用TSPI_lineForward的效果與提供 NULLlpForwardList 參數的效果相同;它會取消目前生效的所有轉送。

由於傳回 lphdConsultCall 的 NULL 值是 TAPI 是否建立諮詢呼叫的唯一方式，因此服務提供者無法使用 NULL 作為呼叫句柄。

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