TSPI_lineMonitorTones 函数 (tspi.h)

项目
03/09/2024

TSPI_lineMonitorTones 函数启用和禁用对调用中带内音的检测。每次检测到指定的音调时，都会通过 TAPI 向客户端应用程序发送一条消息。

语法

LONG TSPIAPI TSPI_lineMonitorTones(
  HDRVCALL                hdCall,
  DWORD                   dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD                   dwNumEntries
);

参数

hdCall

要对其执行音调检测的调用的句柄。 hdCall 的调用状态可以是空闲状态以外的任何状态。

dwToneListID

此音调列表的唯一标识符。一次可以显示多个音调列表。服务提供商必须将具有相同 dwToneListID 的任何旧列表替换为新音调列表。如果 lpToneList 为 NULL，则直接删除包含 dwToneListID 的音调列表。在任何情况下，具有不同 dwToneListID的其他音调列表都保持不变。

lpToneList

要监视的音调列表，类型为 LINEMONITORTONE。此列表中的每个音调都有一个应用程序定义的标记字段，用于标识列表中的单个音调，以便报告音调检测。通过使用 lpToneList 的 NULL 或另一个音调列表调用此操作，取消或更改正在进行的音调监视。服务提供商必须将音调列表复制到自己的内存中供以后引用，而不是简单地将指针保留在应用程序内存中。

dwNumEntries

lpToneList 中的条目数。如果 lpToneList 为 NULL，则忽略 dwNumEntries 参数。调用此函数时，TAPI 不会验证此参数。

返回值

如果函数成功，则返回零;如果发生错误，则返回错误号。可能的返回值如下所示：

LINEERR_INVALCALLHANDLE、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALCALLSTATE、LINEERR_OPERATIONFAILED、LINEERR_INVALTONE、LINEERR_RESOURCEUNAVAIL、LINEERR_NOMEM、LINEERR_INVALPOINTER。

注解

此函数在正确启动音调监视时返回零 (成功) ，而不是终止音调监视时返回。与媒体监视一样，对于给定的音调列表，音调监视将一直有效，直到通过调用具有相同 dwToneListID的TSPI_lineMonitorTones和另一个音调列表 (或 null 音调列表) ，或直到呼叫转换为空闲状态为止。

尽管可以在除空闲之外的任何调用状态中调用此函数，但通常只能在调用处于连接状态时检测到音调。音调检测通常需要计算资源。根据服务提供商和争夺此类资源的其他活动，可以检测到的音调数可能会随时间而变化。此外，可以消耗同等数量的资源来监视单个三重频率音和三个单频率音。如果资源过度提交，服务提供商将返回LINEERR_RESOURCEUNAVAIL。

服务提供商同时监视所有音调列表中的所有音调。检测到音调时，将使用 LINE_MONITORTONE 消息单独报告每个音调列表中的每个匹配音调。每个音调报表都包含音调列表标识符和特定于应用程序的标记。某些服务提供商可能无法区分非常接近的音调，因此，即使对于描述不完全相同的音调，也可能报告多个匹配项。

注意TSPI_lineMonitorTones 还用于检测静音。静音指定为具有所有零频率的音调。

TAPI 级别的相应函数不包含 dwToneListID 参数。在 TSPI 接口中包含此参数允许 TAPI 将所有音调监视列表的联合从所有应用程序转发给服务提供商，同时仍保留根据应用程序筛选和转发音调检测事件的能力。这为服务提供商设计人员提供了最大的灵活性，可以确定他们可以区分非常接近的音调的程度，因为 TAPI 不会假设哪些语气描述被视为相同。