lineHandoff 函式 (tapi.h)

lineHandoff函式會提供另一個應用程式指定呼叫的擁有權。 應用程式可以直接由檔案名指定,或間接指定為處理指定媒體模式呼叫的最高優先順序應用程式。

語法

LONG lineHandoff(
  HCALL  hCall,
  LPCSTR lpszFileName,
  DWORD  dwMediaMode
);

參數

hCall

要交接之呼叫的控制碼。 應用程式必須是呼叫的擁有者。 hCall的撥號狀態可以是任何狀態。

lpszFileName

Null終止字串的指標。 如果這個指標參數不是Null,它會包含應用程式檔案名,而該應用程式是交接的目標。 如果 為 Null,則交接目標是已開啟指定媒體模式之擁有者許可權行的最高優先順序應用程式。 有效的檔案名不包含檔案的路徑。

dwMediaMode

用來識別間接交接目標的媒體模式。 dwMediaMode參數會間接識別接收呼叫擁有權的目標應用程式。 如果 lpszFileName 不是 Null,則會忽略此參數。 此參數只會使用其中一個 LINEMEDIAMODE_常數

傳回值

如果要求成功或發生錯誤,則傳回零。 可能的傳回值為:

LINEERR_INVALCALLHANDLE、LINEERR_OPERATIONFAILED、LINEERR_INVALMEDIAMODE、LINEERR_TARGETNOTFOUND、LINEERR_INVALPOINTER、LINEERR_TARGETSELF、LINEERR_NOMEM、LINEERR_UNINITIALIZED、LINEERR_NOTOWNER。

備註

lineHandoff函式會傳回LINEERR_TARGETSELF,如果呼叫的應用程式嘗試間接交接 (,請將lpszFileName參數設定為Null) ,而 TAPI 判斷應用程式本身是指定媒體模式的最高優先順序應用程式。 如果傳回LINEERR_TARGETNOTFOUND,則找不到通話交接的目標。 如果具名應用程式未開啟與lineOpen之 dwPrivileges參數中的 LINECALLPRIVILEGE_OWNER 位相同的行,就會發生此情況。 或者,在媒體模式交接的情況下,沒有任何應用程式開啟了與lineOpen之 dwPrivileges參數中的 LINECALLPRIVILEGE_OWNER 位相同的行,以及在lineOpendwMediaModes參數中指定的媒體模式。

通話交接可讓呼叫的擁有權在應用程式之間傳遞。 交握有兩種類型。 在第一個類型中,如果應用程式知道目標應用程式的檔案名,它可以直接指定該檔案名。 如果目標應用程式的實例已開啟線路裝置,呼叫的擁有權會傳遞至其他應用程式;否則,交接會失敗,並傳回錯誤。 如果呼叫控制碼與要求交接的應用程式相同檔案名,這個形式的交接就會成功。

第二種類型的交接是以媒體模式為基礎。 在此情況下,應用程式會透過媒體模式間接指定目標應用程式。 目前開啟該媒體模式之線條裝置的最高優先順序應用程式是交接的目標。 如果沒有這類應用程式,則傳回失敗,並傳回錯誤。

lineHandoff函式不會變更呼叫的媒體模式。 若要變更呼叫的媒體模式,應用程式應該在呼叫上使用 lineSetMediaMode ,並指定新的媒體模式。 這會將呼叫的媒體模式變更為儲存在呼叫 的 LINECALLINFO 結構中。

如果交接成功,接收的應用程式會收到呼叫 的LINE_CALLSTATE 訊息。 此訊息表示接收端應用程式具有呼叫 (dwParam3) 的擁有者許可權。 此外,呼叫的擁有者和/或監視器數目可能已變更。 這是由 LINE_CALLINFO 訊息所報告,而接收的應用程式接著可以叫用 lineGetCallStatuslineGetCallInfo ,以擷取所接收呼叫的詳細資訊。

接收應用程式應該先檢查 LINECALLINFO中的媒體模式。 如果只設定單一媒體模式旗標,則呼叫會正式屬於該媒體模式,而且應用程式可以據以採取行動。 如果已設定 UNKNOWN 和其他媒體模式旗標,則呼叫的媒體模式會正式為 UNKNOWN,但假設其為 LINECALLINFO中設定旗標的其中一種媒體模式。 應用程式應該假設它應該探查最高優先順序媒體模式。

如果探查成功 (該媒體模式或另一個) ,應用程式應該將 LINECALLINFO 中的媒體模式成員設定為可辨識的單一媒體模式。 如果媒體模式旗標符合 LINECALLINFO 媒體模式,則應用程式可以據以採取行動。 如果它決定另一個媒體模式,它必須先接聽該媒體模式的呼叫。

如果探查失敗,應用程式應該清除 LINECALLINFO 中的對應媒體模式旗標,並交出呼叫,並將 dwMediaMode 指定為 LINEMEDIAMODE_UNKNOWN。 它也應該將其呼叫控制碼解除配置 (或還原回監視) 。

如果沒有任何媒體模式成功進行判斷,則媒體應用程式嘗試將呼叫交給 UNKNOWN 時,只有 UNKNOWN 旗標會保留在 LINECALLINFO 的媒體模式欄位中。 如果應用程式是唯一的通話擁有者,最後一 行Handoff 就會失敗。 這會通知應用程式應該卸載呼叫,並解除配置其控制碼,在此情況下會放棄呼叫。 這項作業不會變更叫用應用程式對呼叫的許可權,但應用程式可以使用 lineSetCallPrivilege將其許可權變更為呼叫。

規格需求

   
目標平台 Windows
標頭 tapi.h
程式庫 Tapi32.lib
Dll Tapi32.dll

另請參閱

基本電話語音服務參考

遞交概觀

LINECALLINFO

TAPI 2.2 參考概觀

lineGetCallStatus

lineOpen

lineSetCallPrivilege

lineSetMediaMode