TSPI_linePickup 函数 (tspi.h)

项目
03/03/2024

TSPI_linePickup 函数在指定的目标地址接收呼叫警报，并返回接听呼叫的呼叫句柄。如果使用 lpszDestAddress 参数的 NULL 调用，则执行组拾取。如果设备功能需要， lpszGroupID 指定警报站所属的组标识符。

语法

LONG TSPIAPI TSPI_linePickup(
  DRV_REQUESTID dwRequestID,
  HDRVLINE      hdLine,
  DWORD         dwAddressID,
  HTAPICALL     htCall,
  LPHDRVCALL    lphdCall,
  LPCWSTR       lpszDestAddress,
  LPCWSTR       lpszGroupID
);

参数

dwRequestID

异步请求的标识符。

hdLine

要接听调用的行的句柄。

dwAddressID

要发起取件的 hdLine 上的地址。地址标识符与地址永久关联;标识符在操作系统升级中保持不变。

htCall

新调用的 TAPI 句柄。服务提供商必须保存此内容，并在对 LINEEVENT 过程报告调用事件的所有后续调用中使用它。

lphdCall

指向 HDRVCALL 的指针，表示服务提供商的调用标识符。在此过程返回之前，服务提供商必须使用调用的句柄填充此位置。如果函数导致错误，TAPI 将忽略此句柄。

lpszDestAddress

指向 以 null 结尾的 Unicode 字符串的指针，该字符串包含要接听其调用的地址。地址是标准链接格式。

lpszGroupID

指向 以 null 结尾的 Unicode 字符串的指针，该字符串包含警报站所属的组标识符。某些交换机需要此参数才能接听当前应答组外部的呼叫。

注意lpszGroupID 可以通过 lpszDestAddress 的 NULL 指针自行指定。或者，如果设备需要，除了 lpszDestAddress 之外，还可以指定 lpszGroupID。它本身也可以是 NULL 。

返回值

如果发生错误，则返回 dwRequestID 或错误号。如果函数成功，相应ASYNC_COMPLETION的 lResult 实际参数为零;如果发生错误，则为错误号。可能的返回值如下所示：

LINEERR_INVALLINEHANDLE、LINEERR_NOMEM、LINEERR_INVALADDRESSID、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALADDRESS、LINEERR_OPERATIONFAILED、LINEERR_INVALGROUPID、LINEERR_RESOURCEUNAVAIL。

注解

成功接听呼叫后，服务提供商会通知 TAPI LINE_CALLSTATE 有关呼叫状态更改的消息。 LINECALLINFO 结构提供有关接听的呼叫的信息。其中列出了呼叫为取件的原因。此结构可通过调用 TSPI_lineGetCallInfo 获得。

如果可以使用TSPI_linePickup来接听用户已听觉检测到呼叫等待信号但提供商无法执行检测的呼叫，则服务提供商在 LINEADDRESSCAPS 结构中将LINEADDRCAPFLAGS_PICKUPCALLWAIT设置为 TRUE。这为用户提供了一种应答等待呼叫的机制，即使服务提供商无法检测到呼叫等待信号也是如此。当 TSPI_linePickup 用于接听呼叫等待呼叫时， lpszDestAddress 和 lpszGroupID 指针参数均为 NULL。服务提供商为等待呼叫创建新的呼叫句柄，并将该句柄传递给 lphdCall 中的用户。 dwAddressID 参数通常为零 (尤其是在) 的单行住宅案例中。

使用TSPI_linePickup接听第二个呼叫后，可以使用TSPI_lineSwapHold在它们之间切换。 TSPI_lineDrop 可用于删除一个 (并切换到另一个) ，依此类推。如果用户想要删除当前呼叫并接听第二个呼叫，则当他们听到等待呼叫的蜂鸣声时，会调用 TSPI_lineDrop ，等待第二个呼叫响铃，然后在新的呼叫句柄上调用 TSPI_lineAnswer 。服务提供商在 LINEADDRESSSTATUS 的 dwAddressFeatures 成员中设置LINEADDRFEATURE_PICKUP标志，以指示实际可以进行取件。

此函数不同于相应的 TAPI 函数，因为它遵循 TSPI 模型，以开始调用的生存期。 TAPI 和服务提供商交换不透明的句柄，表示相互调用。此外，允许服务提供商在从此过程返回之前对新调用执行回调。在任何情况下，服务提供商还必须将其返回的句柄视为“无效”，直到匹配 ASYNC_COMPLETION 消息报告成功。换句话说，它不得为新调用发出任何 LINEEVENT 消息，也不得将其包含在该行的消息或状态数据结构中的呼叫计数中。