lineHandoff 函式 (tapi.h)

發行項
03/05/2024

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 位相同的行，並在lineOpen的 dwMediaModes 參數中指定媒體模式。

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

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

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

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

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

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

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

如果沒有任何媒體模式成功進行判斷，當媒體應用程式嘗試將呼叫交給 UNKNOWN 時，只有 UNKNOWN 旗標會保留在 LINECALLINFO 的媒體模式欄位中。如果應用程式是唯一呼叫的剩餘擁有者，則最終 lineHandoff 會失敗。這會通知應用程式應該卸除呼叫並解除分配其句柄，在此情況下會放棄呼叫。此作業不會變更叫用應用程式至呼叫的許可權，但應用程式可以使用 lineSetCallPrivilege將其許可權變更為呼叫。