TSPI_lineForward函数 (tspi.h)

项目
03/03/2024

TSPI_lineForward 函数根据指定的转发指令，转发调用指定行上的指定地址。当转发源地址 (dwAddressID) 时，该地址的指定传入呼叫将通过开关偏转到另一个号码。此函数提供向前和请勿打扰功能的组合。此函数还可以取消当前生效的特定转发。

语法

LONG TSPIAPI TSPI_lineForward(
  DRV_REQUESTID           dwRequestID,
  HDRVLINE                hdLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  HTAPICALL               htConsultCall,
  LPHDRVCALL              lphdConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

参数

dwRequestID

异步请求的标识符。

hdLine

要转发的行的服务提供商句柄。

bAllAddresses

指定是转发行上的所有发源地址还是仅转发指定的地址。如果为 TRUE，则转发行上的所有地址并忽略 dwAddressID ;如果 为 FALSE，则仅转发指定为 dwAddressID 的地址。调用此函数时，TAPI 不会验证此参数。

dwAddressID

要转发传入呼叫的指定行上的地址。如果 bAllAddresses 为 TRUE，则忽略此参数。调用此函数时，TAPI 不会验证此参数。

地址标识符与地址永久关联;标识符在操作系统升级中保持不变。

lpForwardList

指向 LINEFORWARDLIST 类型的可变大小数据结构的指针，该结构描述特定的转发指令。

dwNumRingsNoAnswer

指定传入呼叫被视为“无应答”之前的响铃数。如果 dwNumRingsNoAnswer 在范围外，则实际值设置为允许范围内最接近的值。调用此函数时，TAPI 不会验证此参数。

htConsultCall

如果此类调用必须由服务提供商创建，则新调用的 TAPI 句柄。在某些电话环境中，转接呼叫的副作用是创建用于咨询要转发的参与方的咨询呼叫。在此类环境中，服务提供商将创建新的咨询呼叫，并且必须保存此值，并在对呼叫上的 LINEEVENT 过程报告事件的所有后续调用中使用它。如果未创建咨询调用，则服务提供商可以忽略此值。

lphdConsultCall

指向 HDRVCALL 的指针，表示服务提供商的调用标识符。在电话环境中，转发呼叫具有创建用于咨询被转发方的咨询呼叫的副作用，服务提供商必须在此过程返回之前用其呼叫句柄填充此位置。允许服务提供商在从此过程返回之前，对新调用执行回调。如果未创建咨询调用，则 HDRVCALL 必须保留 为 NULL。

lpCallParams

指向 LINECALLPARAMS 类型的结构的指针。服务提供商会忽略此指针，除非 lineForward 要求建立对转发目标 (的调用并返回 lphdConsultCall， 在这种情况下 ，lpCallParams 是可选的) 。如果 为 NULL，则使用默认调用参数。否则，指定的调用参数用于建立 htConsultCall。

返回值

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

LINEERR_INVALLINEHANDLE、LINEERR_NOMEM、LINEERR_INVALADDRESS、LINEERR_OPERATIONUNAVAIL、LINEERR_INVALADDRESSID、LINEERR_OPERATIONFAILED、LINEERR_INVALCOUNTRYCODE、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPARAM、LINEERR_STRUCTURETOOSMALL。

注解

如果指定的正向列表参数包含无效信息，则服务提供程序将返回LINEERR_INVALPARAM。

如果服务提供商返回LINEERR_INVALADDRESS，则不执行拨号。

服务提供商将成功返回给此函数，以仅指示请求被服务提供商接受，而不是在交换机上设置转发。发送 LINE_ADDRESSSTATE (转发) 消息，以提供在交换机上设置转发。

一个或多个地址的转发一直有效，直到再次调用此函数。最新的转发列表将替换任何有效的旧转发列表。如果调用此函数，将 NULL 指针指定为 lpForwardList，则服务提供商应取消当时正在执行的任何转发。如果为转发列表中的某个条目指定 NULL 目标地址，则该操作将充当“请勿打扰”。

地址的转发状态也可能受到外部影响，例如，通过交换机上的管理操作或来自另一个工作站的用户。服务提供商可能无法意识到此状态更改，并且可能无法与交换机已知的转发状态保持同步。提供程序必须始终指示它知道为 true 的内容，并指示转发状态未知，否则。

由于服务提供商可能不知道地址的转发状态，并且毫无疑问 (，因此它可能已以未知方式转发或意外转发) ， 因此TSPI_lineForward 成功，除非未能设置新的转发指令。换句话说，请求在实际上没有转发时取消所有转发。这是因为没有不可原谅的：只能调用一组新的转发指令。

此操作的成功或失败不取决于前一组转发指令，在设置不同的转发指令时也是如此。如有必要，在设置新的转发指令之前，提供程序应“不预知一切”。由于这在模拟电话环境中可能需要一些时间，因此提供商可能还希望将当前转发与新转发进行比较，并且仅向交换机发出指令以进入最终状态， (使未更改的转发不受影响) 。

当 LINEFORWARDLIST 的 dwNumEntries 设置为零时调用TSPI_lineForward与提供 NULLlpForwardList 参数的效果相同;它取消当前生效的所有转发。

由于返回到 lphdConsultCall 的 NULL 值是 TAPI 确定服务提供商是否创建了咨询呼叫的唯一方法，因此服务提供商不能将 NULL 用作呼叫句柄。

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