lineDial 函式 (tapi.h)

發行項
08/26/2023

lineDial函式會撥動指定呼叫上的指定可撥號號碼。

語法

LONG lineDial(
  HCALL  hCall,
  LPCSTR lpszDestAddress,
  DWORD  dwCountryCode
);

參數

hCall

處理要撥打號碼的呼叫。應用程式必須是呼叫的擁有者。 hCall的撥號狀態可以是閑置和中斷連線以外的任何狀態。

lpszDestAddress

使用標準可撥號號碼格式的目的地。

dwCountryCode

目的地的國家/地區代碼。實作會使用此位址來選取目的地位址的呼叫進度通訊協定。如果指定 0 的值，則會使用服務提供者定義的預設呼叫進度通訊協定。

傳回值

如果函式是以非同步方式完成，則傳回正要求識別碼，如果發生錯誤，則傳回負錯誤號碼。如果函式成功或發生錯誤，則對應LINE_REPLY訊息的dwParam2參數為零。可能的傳回值為：

LINEERR_ADDRESSBLOCKED、LINEERR_INVALPOINTER、LINEERR_DIALBILLING、LINEERR_NOMEM、LINEERR_DIALDIALTONE、LINEERR_NOTOWNER、LINEERR_DIALPROMPT、LINEERR_OPERATIONFAILED、LINEERR_DIALQUIET、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALCALLHANDLE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALCALLSTATE、LINEERR_UNINITIALIZED LINEERR_INVALCOUNTRYCODE。

備註

如果傳回LINEERR_INVALADDRESS，則尚未完成撥號。如果傳回LINEERR_DIALBILLING、LINEERR_DIALQUIET、LINEERR_DIALDIALTONE或LINEERR_DIALPROMPT，則不會發生 lineDial 所執行的動作。例如，在發生違規字元之前，沒有可撥號位址、沒有攔截狀態已變更等等。

lineDial函式用於在現有的呼叫外觀上撥號。例如，在為轉移或會議設定通話之後，會自動設定諮詢通話，而 lineDial 函式會用來執行此諮詢通話的撥號。如果行的裝置功能允許，可以在多階段撥號過程中多次叫用 lineDial 函式。此外，可以在以 CRLF 分隔的單一撥號字串中提供多個位址。提供反向多工處理的服務提供者可以建立每個位址的個別實體呼叫，並可傳回單一呼叫控制碼，以匯總應用程式的所有呼叫。所有位址都會使用相同的國家或地區代碼。

將位址傳遞至服務提供者之後，即會被視為完成撥號;不是在呼叫最後連接之後。提供反向多工處理的服務提供者可以一次提供多個位址。服務提供者會將LINE_CALLSTATE訊息傳送至應用程式，以通知其呼叫進度。若要在建立呼叫時中止呼叫嘗試，叫用應用程式應該使用 lineDrop。

應用程式可以將lineDial函式的lpszDestAddress參數設定為空字串的位址，以指出撥號已完成，但只有在前一次呼叫lineMakeCall和lineDial函式時，lpszDestAddress已使用分號終止。

lineDial函式也可用於部分撥號。若要使用部分撥號起始呼叫，應用程式會呼叫 lineMakeCall 並指定部分撥號字串。部分撥號字串是由分號終止的任何撥號字串。呼叫通常會轉換成LINECALLSTATE_DIALING之後，可以呼叫 lineDial 來指定更多撥號字串，每個字串都會以分號終止。撥號完成的方式是使用未以分號終止的撥號字串來呼叫 lineDial (，例如空字串) 。這項技術可讓應用程式與使用者執行互動式部分撥號，或啟用比 TSP 更複雜的撥號功能。

如果 null 目的地字串，或以分號 (「;」結尾的空字串) 會在 lineMakeCall 中輸入應用程式轉換為LINE_CALLSTATE_DIALTONE。 lineDial函式可以在此狀態下呼叫，以輸入單一撥號字串或多個部分撥號字串，每個字串都是以分號分隔。應用程式會在輸入第一個數位之後轉換為LINECALLSTATE_DIALING狀態。

注意只有在呼叫位於 LINECALLSTATE_DIALING 或 LINE_CALLSTATE_DIALTONE 時，才能使用 lineDial 函式。如果在連線 (LINECALLSTATE_CONNECTED) 呼叫時需要 DTMF，請使用 lineGenerateDigits。