TSPI_lineSetupConference 函数 (tspi.h)

项目
03/03/2024

TSPI_lineSetupConference 函数为添加第三方设置电话会议。

语法

LONG TSPIAPI TSPI_lineSetupConference(
  DRV_REQUESTID          dwRequestID,
  HDRVCALL               hdCall,
  HDRVLINE               hdLine,
  HTAPICALL              htConfCall,
  LPHDRVCALL             lphdConfCall,
  HTAPICALL              htConsultCall,
  LPHDRVCALL             lphdConsultCall,
  DWORD                  dwNumParties,
  LPLINECALLPARAMS const lpCallParams
);

参数

dwRequestID

异步请求的标识符。

hdCall

标识会议呼叫的第一方的初始呼叫的句柄。在某些环境中，必须存在呼叫才能启动电话会议。在其他电话环境中，最初不存在任何呼叫， hdCall 保留 为 NULL。 hdCall 的呼叫状态可以连接。

hdLine

发起电话会议的线路设备的句柄（如果 hdCall 为 NULL）。如果 hdCall 为非 NULL，则忽略 hdLine 参数。服务提供商通过 LINEADDRESSCAPS 数据结构的 setupConfNull 标志报告它支持的模型。

htConfCall

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

lphdConfCall

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

htConsultCall

咨询呼叫的 TAPI 句柄。设置添加新方呼叫时，将自动分配新的临时呼叫 (咨询呼叫) 。服务提供商必须保存 htConsultCall ，并在对新咨询呼叫的 LINEEVENT 过程报告事件的所有后续调用中使用它。

lphdConsultCall

指向 HDRVCALL 的指针，表示服务提供商的呼叫标识符。设置添加新方呼叫时，将自动分配新的临时呼叫 (咨询呼叫) 。在此过程返回之前，服务提供商必须使用新咨询调用的句柄填充此位置。如果函数导致错误，TAPI 将忽略此句柄。 hdConsultCall 的调用状态不适用。

dwNumParties

电话会议的预期派对数。服务提供商可以随意使用此号码。例如，服务提供商可以忽略它，或将其用作在交换机内分配适当大小的会议网桥的提示。调用此函数时，TAPI 不会验证此参数。

lpCallParams

指向 LINECALLPARAMS 结构的指针，其中包含在建立咨询调用时要使用的调用参数。如果不需要任何特殊的调用设置参数，并且服务提供商使用默认参数，则此参数设置为 NULL 。

返回值

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

LINEERR_INVALCALLHANDLE、LINEERR_INVALADDRESSMODE、LINEERR_INVALLINEHANDLE、LINEERR_INVALBEARERMODE、LINEERR_INVALCALLSTATE、LINEERR_INVALCALLPARAMS、LINEERR_CALLUNAVAIL、LINEERR_INVALLINESTATE、LINEERR_CONFERENCEFULL、LINEERR_INVALMEDIAMODE、LINEERR_NOMEM、LINEERR_INVALRATE、LINEERR_OPERATIONUNAVAIL、LINEERR_INUSE、LINEERR_OPERATIONFAILED、LINEERR_RATEUNAVAIL、LINEERR_RESOURCEUNAVAIL、LINEERR_USERUSERINFOTOOBIG、LINEERR_BEARERMODEUNAVAIL。

注解

如果包含会议呼叫的行的指定行句柄无效，则服务提供商将返回LINEERR_INVALLINEHANDLE。此错误还可能表明，电话环境需要初始线路来设置会议，但提供了非 NULL 呼叫句柄。

如果电话环境需要初始调用来设置会议，但改为提供了 NULL 呼叫句柄，则服务提供商将返回LINEERR_INVALCALLHANDLE。

TSPI_lineSetupConference 提供了两种方法来建立新的电话会议，具体取决于是否需要正常的双方通话才能预先存在。从现有两方呼叫设置电话会议时， hdCall 参数是一个有效的呼叫句柄，最初由 TSPI_lineSetupConference 请求添加到电话会议， hdLine 将被忽略。在电话会议设置未从现有呼叫开始的交换机上， hdCall 必须为 NULL ，并且必须指定 hdLine 以标识要启动电话呼叫的线路设备。在任一情况下，都会分配咨询呼叫来连接到要添加到呼叫的参与方。 TAPI 可以使用 TSPI_lineDial 拨打另一方的地址。

如果会议呼叫) 进入会议状态，会议呼叫通常会转换为 onHoldPendingConference 状态、咨询呼叫拨号状态和初始呼叫 (。

还可以使用解析为三向会议的 TSPI_lineCompleteTransfer 函数设置电话会议。

TAPI 可以使用 TSPI_lineSwapHold在咨询呼叫和电话会议之间切换。

TSPI_lineUnhold 函数可以恢复调用状态为 onHoldPendingConference 的调用。如果执行此操作，任何咨询调用通常会进入空闲状态。

可以通过调用 TSPI_lineDrop 来取消咨询呼叫。在拨打咨询呼叫时，现有电话会议通常会转换回连接状态。 TAPI 及其客户端应用程序应观察 LINE_CALLSTATE 消息，以确定调用的确切情况。例如，如果电话会议恢复为常规的两方通话，则会议呼叫将变为空闲状态，原始参与者呼叫可能会还原已连接。

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