lineOpen 函数 (tapi.h)

2024-03-13

lineOpen 函数打开由其设备标识符指定的行设备，并返回相应打开的行设备的行句柄。此行句柄用于线路设备上的后续操作。

语法

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

参数

hLineApp

使用 TAPI 注册应用程序的句柄。

dwDeviceID

标识要打开的线路设备。它可以是有效的设备标识符或值。

值	含义
LINEMAPPER	此值用于在系统中打开支持 lpCallParams 中指定的属性的线路设备。应用程序可以使用 lineGetID 来确定已打开的线路设备的标识符。

lphLine

指向 HLINE 句柄的指针，该句柄随后加载该句柄表示打开的行设备。在开行设备上调用其他函数时，使用此句柄标识设备。

dwAPIVersion

应用程序和电话 API 同意运行的 API 版本号。此数字是使用 lineNegotiateAPIVersion 获取的。

dwExtVersion

应用程序和服务提供商同意运行的扩展版本号。如果应用程序不使用任何扩展，则此数字为零。此数字是使用 lineNegotiateExtVersion 获取的。

dwCallbackInstance

用户实例数据传递回应用程序，每条消息与此行相关联，或者此行上的地址或调用。电话 API 不解释此参数。

dwPrivileges

收到调用通知时应用程序需要的权限此参数包含一个或多个 LINECALLPRIVILEGE_常量。对于使用 TAPI 版本 2.0 或更高版本的应用程序，此参数的值还可以与一个或多个 LINEOPENOPTION_常量组合使用。

如果指定了 LINEOPENOPTION_SINGLEADDRESS 选项，则应用程序仅对由 lpCallParams 参数指向的 LINECALLPARAMS 结构中 dwAddressID 成员指定的地址上显示的新调用感兴趣，而 lpCallParams 参数 (必须) 指定。

如果指定了LINEOPENOPTION_SINGLEADDRESS，但 lpCallParams 无效或包含的 dwAddressID 在行中不存在，则打开失败并LINERR_INVALADDRESSID。

除了将 LINECALLPARAMS 结构的 dwAddressID 成员设置为所需地址外，应用程序还必须将 LINECALLPARAMS 中的 dwAddressMode 设置为LINEADDRESSMODE_ADDRESSID。

LINEOPENOPTION_SINGLEADDRESS选项仅影响 TAPI 对服务提供商使用 LINE_NEWCALL 消息创建的呼叫的初始呼叫所有权分配。使用 LINECALLPRIVILEGE_MONITOR 打开行的应用程序继续接收对线路上创建的所有调用的监视句柄。此外，应用程序不会以任何方式限制调用或执行影响打开行上其他地址的其他操作。

当仅) (TAPI 2.0 或更高版本指定LINEOPENOPTION_PROXY选项时，应用程序还必须指示它准备处理哪些特定的代理请求。它通过在 lpCallParams 参数中传递指向 LINECALLPARAMS 结构的指针来执行此操作，其中 dwDevSpecificSize 和 dwDevSpecificOffset 成员已设置为分隔 DWORD的数组。此数组的每个元素应包含 LINEPROXYREQUEST_常量之一。例如，支持所有五个代理相关函数的代理处理程序应用程序将传入包含 5 个 DWORD的数组， (dwDevSpecificSize 为 20 个十进制) 包含五个定义的LINEPROXYREQUEST_值。

代理请求处理程序应用程序可以在有权控制线路设备的任何计算机上运行。但是，请求始终通过服务提供商正在执行的服务器路由，该服务器实际上控制线路设备。因此，如果处理代理请求的应用程序 (（如 ACD 代理控制) ）与服务提供商一起直接在服务器上执行，则最高效。

同一应用程序或其他应用程序打开线路设备并注册以处理与已注册的应用程序相同的代理请求的后续尝试失败，LINEERR_NOTREGISTERED。

若要停止处理线路上的请求，应用程序只需调用 lineClose。

其他标志组合返回LINEERR_INVALPRIVSELECT错误。

dwMediaModes

应用程序感兴趣的媒体类型或模式。此参数用于将应用程序注册为指定媒体类型的传入呼叫和呼叫切换的潜在目标。仅当 dwPrivileges 中的位LINECALLPRIVILEGE_OWNER设置为 (并忽略) 时，此参数才有意义。此参数使用一个或多个 LINEMEDIAMODE_常量。

lpCallParams

指向 LINECALLPARAMS 类型的结构的指针。仅当使用 LINEMAPPER 或 LINEOPENOPTION_PROXY 时才使用此指针;否则 ，将忽略 lpCallParams 。它描述了线路设备应能够提供的调用参数。

返回值

如果请求成功，则返回零;如果发生错误，则返回负错误号。可能的返回值为：

LINEERR_ALLOCATED、LINEERR_LINEMAPPERFAILED、LINEERR_BADDEVICEID、LINEERR_NODRIVER、LINEERR_INCOMPATIBLEAPIVERSION、LINEERR_NOMEM、LINEERR_INCOMPATIBLEEXTVERSION、LINEERR_OPERATIONFAILED、LINEERR_INVALAPPHANDLE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALMEDIAMODE、LINEERR_STRUCTURETOOSMALL、LINEERR_INVALPOINTER、LINEERR_UNINITIALIZED、LINEERR_INVALPRIVSELECT、LINEERR_REINIT、LINEERR_NODEVICE、LINEERR_OPERATIONUNAVAIL。

注解

如果返回LINEERR_ALLOCATED，则由于“永久性”条件（例如串行端口由另一个进程独占打开）而无法打开该行。如果返回LINEERR_RESOURCEUNAVAIL，则由于动态资源过度使用（例如在 DSP 处理器周期或内存中）而无法打开该行。由于监视媒体类型或音调，这种过度承诺可能是暂时的，而其他应用程序对这些活动的更改使得在短时间内重新打开线路成为可能。如果返回LINEERR_REINIT并且已请求 TAPI 重新初始化 (例如，由于添加或删除电话服务提供商) ，则 lineOpen 请求将被拒绝并出现此错误，直到最后一个应用程序使用 lineShutdown) 关闭其 API (的使用;届时，新配置将生效，应用程序再次被允许调用 lineInitializeEx。

打开行始终使应用程序有权对线路上可用的任何地址进行调用。应用程序处理传入呼叫或成为线路上呼叫切换目标的能力由 dwMediaModes 参数确定。 lineOpen 函数将应用程序注册为对监视呼叫或接收属于指定媒体类型的调用的所有权感兴趣。如果应用程序只想监视调用，则可以指定LINECALLPRIVILEGE_MONITOR。如果应用程序只想发出传出调用，它可以指定LINECALLPRIVILEGE_NONE。如果应用程序愿意控制未知媒体类型) (调用的未分类调用，它可以指定LINECALLPRIVILEGE_OWNER和LINEMEDIAMODE_UNKNOWN。否则，应用程序应指定它感兴趣的处理媒体类型。应用程序可以调用 lineSetCallPrivilege 函数来更改LINECALLPRIVILEGES_Constants指定的调用权限。

使用 lineOpen 指定的媒体类型将添加到提供程序的媒体类型监视的默认值，以便确定初始传入呼叫类型。 lineMonitorMedia 函数修改控制LINE_MONITORMEDIA消息的掩码。如果使用所有者权限打开线路设备，并且扩展媒体类型未注册，则返回错误LINEERR_INVALMEDIAMODE。

成功打开线路设备的应用程序始终可以使用带有 NULLhCall) 的 lineMakeCall、lineUnpark、linePickup 和 lineSetupConference (发起调用，并使用 lineForward (假设设备功能、线路状态等) 允许这样做。

单个应用程序可以同时指定多个标志来处理多个媒体类型。如果多个应用程序为同一媒体类型打开同一线路设备，则可能会出现冲突。这些冲突通过用户向应用程序分配相对优先级的优先级方案来解决。用户可以通过调用 lineSetAppPriority 函数来设置应用程序优先级。只有给定媒体类型的最高优先级应用程序才会获得 (未经请求) 该媒体类型的调用的所有权。当传入呼叫首次到达或呼叫转移时，可以接收所有权。调用 lineHandoff 函数将调用的所有权移交给另一个应用程序。如果用户未将优先级分配给应用程序，并且多个应用程序打开同一行设备，则默认情况下，首先调用 lineOpen 的应用程序将具有最高优先级。

任何应用程序 (包括任何较低优先级的应用程序) 始终可以使用 lineGetNewCalls 或 lineGetConfRelatedCalls 获取所有权。如果应用程序在线路上存在调用时打开一行进行监视，则这些现有调用LINE_CALLSTATE消息不会自动生成到新的监视应用程序。应用程序可以查询线路上的当前调用数，以确定存在多少次调用，如果需要，可以调用 lineGetNewCalls 来获取这些调用的句柄。

处理自动语音的应用程序还应选择交互式语音打开模式，并为交互式语音分配最低优先级。原因是服务提供商将所有语音媒体类型报告为交互式语音。如果未知媒体类型的应用程序未执行媒体类型确定，并且没有交互式语音应用程序打开线路设备，则语音呼叫将无法访问自动语音应用程序，并且将被丢弃。

同一应用程序或同一应用程序的不同实例化，可以使用相同或不同的参数多次打开同一行。

当应用程序打开行设备时，它必须指定协商的 API 版本，如果想要使用该行的扩展，则应指定行特定于设备的扩展版本。应使用 lineNegotiateAPIVersion 和 lineNegotiateExtVersion 获取这些版本号。版本号允许将不同的应用程序版本与不同的 API 版本和服务提供程序版本混合和匹配。

LINEMAPPER 允许应用程序间接选择一条线路-通过它从中获取的服务。使用 LINEMAPPER 打开线路设备时，符合以下条件：从 LINECALLPARAMS 数据结构开头到 dwAddressMode 的所有成员都相关。如果 dwAddressMode 为LINEADDRESSMODE_ADDRESSID则表示行上的任何地址都是可以接受的，否则如果 dwAddressMode 是LINEADDRESSMODE_DIALABLEADDR，则指示搜索了) 的特定发源地址 (电话号码，或者如果是特定于提供程序的分机，则 dwOrigAddressSize/Offset 及其引用的变量部分也相关。如果 dwAddressMode 是特定于提供程序的扩展，则 dwDeviceSpecific 可变大小成员中可以包含其他信息。