lineOpen 函数 (tapi.h)

项目
01/23/2023

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

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

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

lphLine

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

dwAPIVersion

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

dwExtVersion

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

dwCallbackInstance

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

dwPrivileges

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

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

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

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

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

当指定LINEOPENOPTION_PROXY选项时， (TAPI 2.0 或更高版本仅) ，应用程序还必须指示它准备处理的特定代理请求。它通过在 lpCallParams 参数中传递指向 LINECALLPARAMS 结构的指针，其中 dwDevSpecificSize 和 dwDevSpecificOffset 成员已设置为分隔 DWORDs 数组。此数组的每个元素应包含 LINEPROXYREQUEST_常量之一。例如，支持所有五个代理相关函数的代理处理程序应用程序将传入五个 DWORDs (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。

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

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

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

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

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

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

LINEMAPPER 允许应用程序通过它想要的服务间接选择一行。使用 LINEMAPPER 打开行设备时，如下所示：通过 dwAddressMode 从 LINECALLPARAMS 数据结构开始的所有成员都相关。如果 dwAddressMode 是LINEADDRESSMODE_ADDRESSID则表示可以接受行上的任何地址，否则如果 dwAddressMode 是LINEADDRESSMODE_DIALABLEADDR，则表示搜索特定起始地址 (电话号码) ，或者如果它是特定于提供程序的扩展，则 dwOrigAddressSize/Offset 和它们引用的变量部分也相关。如果 dwAddressMode 是特定于提供程序的扩展，则可以将其他信息包含在 dwDeviceSpecific 可变大小的成员中。