lineSetMediaControl 函数 (tapi.h)

项目
08/26/2023

lineSetMediaControl 函数在与指定线路、地址或调用关联的媒体流上启用和禁用控制操作。媒体控制操作可以通过检测指定的数字、媒体类型、自定义音调和调用状态来触发。

语法

LONG lineSetMediaControl(
  HLINE                             hLine,
  DWORD                             dwAddressID,
  HCALL                             hCall,
  DWORD                             dwSelect,
  LPLINEMEDIACONTROLDIGIT const     lpDigitList,
  DWORD                             dwDigitNumEntries,
  LPLINEMEDIACONTROLMEDIA const     lpMediaList,
  DWORD                             dwMediaNumEntries,
  LPLINEMEDIACONTROLTONE const      lpToneList,
  DWORD                             dwToneNumEntries,
  LPLINEMEDIACONTROLCALLSTATE const lpCallStateList,
  DWORD                             dwCallStateNumEntries
);

参数

hLine

开行设备的句柄。

dwAddressID

给定开行设备上的地址标识符。地址标识符与地址永久关联;标识符在操作系统升级中保持不变。

hCall

调用的句柄。应用程序必须是呼叫的所有者。 hCall 的调用状态可以是任何状态。

dwSelect

请求的媒体控件是与单个调用相关联，是地址上所有调用的默认值，还是线路上所有调用的默认值。此参数为 1，并且只有一个 LINECALLSELECT_常量。

lpDigitList

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

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

dwDigitNumEntries

lpDigitList 中的条目数。

lpMediaList

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

dwMediaNumEntries

lpMediaList 中的条目数。

lpToneList

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

dwToneNumEntries

lpToneList 中的条目数。

lpCallStateList

指向具有 LINEMEDIACONTROLCALLSTATE 类型条目的数组的指针。数组包含 dwCallStateNumEntries 条目。每个条目都包含一个调用状态和一个媒体控件操作。每当给定的调用转换到列表中的某个调用状态时，就会调用相应的媒体控制操作。

dwCallStateNumEntries

lpCallStateList 中的条目数。

返回值

如果请求成功，则返回零;如果发生错误，则返回负错误号。可能的返回值为：

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

注解

如果媒体控件已正确启动，则 lineSetMediaControl 函数被视为成功，而不是当任何媒体控件生效时。正在进行中的媒体控件已更改，或者通过使用不同的参数或 NULL再次调用此函数来取消。如果一个或多个参数 lpDigitList、 lpMediaList、 lpToneList 和 lpCallStateList 为 NULL，则禁用相应的数字、媒体类型、音调或调用状态触发的媒体控件。若要仅修改媒体控件参数的一部分，同时保留剩余设置，应用程序应调用 lineSetMediaControl，为必须保持有效状态的部分提供以前的参数，并为要修改的部分提供新参数。

如果选择 了 hCall ，并且调用终止或应用程序解除分配其句柄，则会取消对该调用的媒体控制。

原则上，所有属于呼叫所有者的应用程序都允许在调用上发出媒体控制请求。只有单个媒体控制请求可以在所有拥有该调用的应用程序的调用中未完成。每次调用 LineSetMediaControl 时，新请求都会覆盖调用时生效的任何媒体控件，无论是由调用应用程序还是由任何其他拥有的应用程序设置。

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

服务提供商是否支持媒体控制是一项设备功能。