lineHandoffA 函式（tapi.h）

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

語法

LONG lineHandoffA(
  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，則找不到呼叫交接的目標。如果具名應用程式未開啟與 dwPrivilegeslineOpen中LINECALLPRIVILEGE_OWNER位相同的行，就會發生這種情況。或者，在媒體模式交接的情況下，沒有任何應用程式在 dwPrivileges lineOpen 的 LINECALLPRIVILEGE_OWNER 位開啟同一行，並在 dwMediaModes 參數中指定了 lineOpen的媒體模式。

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

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

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

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

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

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

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

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

注意

tapi.h 標頭會將lineHandoff定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。