TSPI_lineSetMediaControl 函数 (tspi.h)

项目
08/26/2023

TSPI_lineSetMediaControl 函数对与指定线路、地址或呼叫关联的媒体流启用和禁用控制操作。媒体控制操作可以通过检测指定的数字、媒体类型、自定义音调和调用状态来触发。新的指定媒体控件将替换在此请求之前对此行、地址或调用生效的所有媒体控件。

语法

LONG TSPIAPI TSPI_lineSetMediaControl(
  HDRVLINE                          hdLine,
  DWORD                             dwAddressID,
  HDRVCALL                          hdCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

参数

hdLine

行的句柄。

dwAddressID

给定开行设备上的地址。地址标识符与地址永久关联;标识符在操作系统升级中保持不变。调用此函数时，TAPI 不会验证此参数。

hdCall

调用的句柄。 hdCall 的调用状态可以是任何状态。

dwSelect

指定请求的媒体控制是与单个调用相关联，是地址上所有调用的默认值，还是一行上所有调用的默认值。此参数使用以下 LINECALLSELECT_常量。

lpDigitList

指向数组的指针，该数组包含用于触发媒体控制操作的数字，类型为 LINEMEDIACONTROLDIGIT。每次检测到数字列表中列出的数字时，都会对调用的媒体流执行指定的媒体控制操作。

脉冲模式的有效数字为“0”到“9”。 DTMF 模式的有效数字为“0”到“9”、“A”、“B”、“C”、“D”、“*”、“#”。

dwDigitNumEntries

lpDigitList 中的条目数。调用此函数时，TAPI 不会验证此参数。

lpMediaList

指向具有 LINEMEDIACONTROLMEDIA 类型的条目的数组的指针。数组包含 dwMediaNumEntries 条目。每个条目都包含要监视的媒体类型、特定于媒体类型的信息 (（如持续时间) ）和媒体控件字段。如果检测到列表中的媒体类型，则会对调用的媒体流执行相应的媒体控制操作。

dwMediaNumEntries

lpMediaList 中的条目数。调用此函数时，TAPI 不会验证此参数。

lpToneList

指向具有 LINEMEDIACONTROLTONE 类型条目的数组的指针。数组包含 dwToneNumEntries 条目。每个条目都包含要监视的音调、语气持续时间和媒体控件字段的说明。如果检测到列表中的音调，则会对调用的媒体流执行相应的媒体控制操作。

dwToneNumEntries

lpToneList 中的条目数。调用此函数时，TAPI 不会验证此参数。

lpCallStateList

指向具有 LINEMEDIACONTROLCALLSTATE 类型条目的数组的指针。数组包含 dwCallStateNumEntries 条目。每个条目都包含一个调用状态和一个媒体控件操作。

dwCallStateNumEntries

lpCallStateList 中的条目数。调用此函数时，TAPI 不会验证此参数。

返回值

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

LINEERR_INVALADDRESSID、LINEERR_INVALPOINTER、LINEERR_INVALCALLHANDLE、LINEERR_INVALTONELIST、LINEERR_INVALCALLSELECT、LINEERR_NOMEM、LINEERR_INVALCALLSTATELIST、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALDIGITLIST、LINEERR_OPERATIONFAILED、LINEERR_INVALLINEHANDLE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALMEDIALIST。

注解

当媒体控制正确启动时，此函数返回零 (成功) ，而不是当任何媒体控制生效时。当使用不同的参数或 NULL再次调用此函数时，正在进行中的媒体控件将更改或取消。

一次调用中只能发出单个媒体控制请求。请求替换可能未完成的任何请求。

根据与此类资源竞争的服务提供商和其他活动，可以进行的同步检测量可能会随时间而变化。如果服务提供程序资源过度提交，则返回LINEERR_RESOURCEUNAVAIL。

服务提供商是否支持媒体控制是 LINEDEVCAPS 中指示的设备功能。

每次调用 TSPI_lineSetMediaControl 时，新请求都会覆盖当前生效的任何媒体控件。如果一个或多个参数 lpDigitList、 lpMediaList、 lpToneList 和 lpCallStateList 为 NULL，则禁用相应的数字、媒体类型、音调或调用状态触发的媒体控件。若要仅修改媒体控制参数的一部分，同时保留其余设置，应用程序应调用 TSPI_lineSetMediaControl 为必须保持有效的部分提供以前的参数，并为要修改的部分提供新参数。