TSPI_lineMakeCall函式 (tspi.h)

發行項
03/09/2024

TSPI_lineMakeCall函式會將呼叫放在指定之目的地位址的指定行上。您可以選擇性地指定呼叫參數，但要求預設呼叫設定參數以外的任何專案。

語法

LONG TSPIAPI TSPI_lineMakeCall(
  DRV_REQUESTID          dwRequestID,
  HDRVLINE               hdLine,
  HTAPICALL              htCall,
  LPHDRVCALL             lphdCall,
  LPCWSTR                lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

參數

dwRequestID

異步要求的標識碼。

hdLine

要產生新呼叫之行的句柄。

htCall

新呼叫的 TAPI 句柄。服務提供者必須儲存此專案，並在呼叫上報告事件的所有後續 LINEEVENT 過程呼叫中使用它。

lphdCall

呼叫句柄的指標。服務提供者必須在傳回此程式之前，填入此位置的呼叫句柄。如果函式產生錯誤，TAPI 會忽略此句柄。

lpszDestAddress

指定目的地位址之 Null 終止 Unicode 字串的指標。這會遵循標準可撥號號碼格式。此指標可以指定為非撥號位址的 NULL， (為使用熱電話，這一律會自動連線到預先定義的號碼) ，或使用 TSPI_lineDial執行所有撥號時。在後者的情況下， TSPI_lineMakeCall 會配置一個可用的通話外觀，在撥號開始之前，通常會維持在 撥號字元 狀態。具有反向多任務功能的服務提供者可讓應用程式一次指定多個位址。

dwCountryCode

被呼叫者的國家/地區代碼。如果指定值為 0，實作會使用預設值。

lpCallParams

LINECALLPARAMS 結構的指標。此結構可讓 TAPI 指定要如何設定呼叫。如果指定 NULL，則會建立預設的 3.1kHz 語音通話，並選取行上的任意原點位址。此結構會選取呼叫的持有人模式、數據速率、預期的媒體類型、原點位址、呼叫端標識符信息的封鎖，以及撥號參數等元素。

傳回值

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

LINEERR_ADDRESSBLOCKED、LINEERR_INVALLINESTATE、LINEERR_BEARERMODEUNAVAIL、LINEERR_INVALRATE、LINEERR_CALLUNAVAIL、LINEERR_INVALLINEHANDLE、LINEERR_DIALBILLING、LINEERR_INVALADDRESS、LINEERR_DIALQUIET、LINEERR_INVALADDRESSID LINEERR_DIALDIALTONE、LINEERR_INVALCALLPARAMS、LINEERR_DIALPROMPT LINEERR_NOMEM、LINEERR_INUSE LINEERR_OPERATIONUNAVAIL、LINEERR_INVALADDRESSMODE、LINEERR_OPERATIONFAILED LINEERR_INVALBEARERMODE LINEERR_RESOURCEUNAVAIL LINEERR_INVALCOUNTRYCODE、LINEERR_RATEUNAVAIL、LINEERR_INVALMEDIAMODE、LINEERR_USERUSERINFOTOOBIG。

備註

如果行目前不是可執行此作業的狀態，則服務提供者會傳回LINEERR_INVALLINESTATE。目前有效的作業清單可以在LINEDEVSTATUS結構的LINEFEATURE類型 (的 dwLineFeatures 成員) 中找到。 (呼叫 TSPI_lineGetLineDevStatus 會更新 LINEDEVSTATUS.) 中的資訊

如果服務提供者傳回LINEERR_DIALBILLING、LINEERR_DIALQUIET、LINEERR_DIALDIALTONE或LINEERR_DIALPROMPT，則它應該不會執行 TSPI_lineMakeCall所執行的任何動作。例如，沒有部分撥號，也不會關閉hook。這是因為服務提供者應該先預先掃描不支援字元的數位。

TSPI_lineMakeCall將 SUCCESS 回復回呼訊息傳回給應用程式之後，服務提供者必須將LINE_CALLSTATE訊息傳送至傳入TSPI_lineOpen的 lpfnEventProc，以通知 TAPI 關於呼叫進度。典型的報告序列可能是撥號音、撥號、繼續、迴響和 已連線;回報的第一個狀態不一定LINECALLSTATE_DIALTONE。服務提供者會選擇報告這些狀態的數目。建議傳送盡可能多，讓應用程式可以採取適當的動作。

服務提供者一開始會在新呼叫上執行媒體監視，至少針對一行上監視的一組媒體類型執行媒體監視。

如果撥號字串為 NULL，服務提供者會將這一行帶到 Comm 型服務提供者的 撥號音 狀態 (，這會牽涉到 ATD) ，並傳送指出LINECALLSTATE_DIALTONE的通話狀態訊息。

如果撥號字串以『;』結尾 (分號) ，服務提供者會撥入部分號碼，並傳送LINECALLSTATE_DIALING訊息。呼叫 TSPI_lineDial完成此呼叫。

如果撥號字串包含服務提供者不支援的字元 (W、@、$、？) ，則服務提供者必須掃描撥號字串，並同步傳回 (同步) 對應至第一個無效字元的錯誤。

如果已設定LINECALLPARAMFLAGS_IDLE旗標，服務提供者必須檢查目前的行狀態， (相當於跳離和音調撥號音) 。如果已設定此IDLE旗標，而且沒有撥號音，則函式會失敗，並出現錯誤LINEERR_CALLUNAVAIL。如果未設定IDLE旗標，或有撥號音，撥號可以繼續。

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