lineOpenA 函数（tapi.h）

2024-11-20

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

语法

LONG lineOpenA(
  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选项，则应用程序仅对 dwAddressID 成员指定的地址上显示的新调用感兴趣，该 LINECALLPARAMS 结构中 lpCallParams 参数所指向的结构（必须指定）。

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

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

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

指定LINEOPENOPTION_PROXY选项（仅 TAPI 2.0 或更高版本）时，应用程序还必须指示它准备处理的特定代理请求。它通过在 lpCallParams 参数中传递一个指向 LINECALLPARAMS 结构的指针，其中 dwDevSpecificSize 和 dwDevSpecificOffset 成员已设置为分隔 DWORD数组。此数组的每个元素应包含 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 请求被拒绝，并出现此错误，直到最后一个应用程序关闭其 API 的使用（使用 lineShutdown）：此时，新配置生效，应用程序再次被允许调用 lineInitializeEx。

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

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

成功打开线路设备的应用程序始终可以使用 lineMakeCall、lineUnpark、linePickup和行启动调用SetupConference（NULLhCall），并使用 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 可变大小的成员中。

注意

tapi.h 标头将 lineOpen 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。