lineHandoff 函数 (tapi.h)

项目
03/13/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 时， LINECALLINFO 的媒体模式字段中仅保留“未知”标志。如果应用程序是调用的唯一剩余所有者，则最后一个 lineHandoff 将失败。这会通知应用程序，它应删除调用并解除分配其句柄，在这种情况下，调用将被放弃。此操作不会更改调用应用程序的权限，但应用程序可以使用 lineSetCallPrivilege 将其权限更改为调用。