TSPI_lineSetupTransfer función (tspi.h)

Artículo
03/08/2023

La función TSPI_lineSetupTransfer inicia una transferencia de la llamada especificada por hdCall. Establece una llamada de consulta, lphdConsultCall, en la que se puede marcar la parte que puede convertirse en el destino de la transferencia.

Sintaxis

LONG TSPIAPI TSPI_lineSetupTransfer(
  DRV_REQUESTID          dwRequestID,
  HDRVCALL               hdCall,
  HTAPICALL              htConsultCall,
  LPHDRVCALL             lphdConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parámetros

dwRequestID

Identificador de la solicitud asincrónica.

hdCall

Identificador de la llamada que se va a transferir. El estado de llamada de hdCall se puede conectar.

htConsultCall

El controlador TAPI para la nueva llamada de consulta temporal. El proveedor de servicios debe guardarlo y usarlo en todas las llamadas posteriores al procedimiento LINEEVENT que notifica eventos en la nueva llamada de consulta.

lphdConsultCall

Puntero a un HDRVCALL que representa el identificador del proveedor de servicios para la nueva llamada de consulta. El proveedor de servicios debe rellenar esta ubicación con su identificador para la nueva llamada de consulta antes de que se devuelva este procedimiento. TAPI omite este identificador si la función produce un error. El estado de llamada de hdConsultCall no es aplicable.

Al configurar una llamada para la transferencia, se asigna automáticamente otra llamada (una llamada de consulta) para permitir que la aplicación (a través de TAPI) marque la dirección (mediante TSPI_lineDial) de la parte a la que se va a transferir la llamada. La parte de origen puede llevar a cabo una conversación a través de esta llamada de consulta antes de completar la transferencia.

Este procedimiento de transferencia puede no ser válido para algunos dispositivos de línea. En lugar de llamar a este procedimiento, ES posible que TAPI tenga que retener una llamada mantenida existente (mediante TSPI_lineUnhold) para identificar el destino de la transferencia. En los conmutadores que admiten la transferencia de llamadas entre direcciones, la llamada de consulta puede existir en una dirección diferente a la que se va a transferir. También puede ser necesario configurar la llamada de consulta como una llamada completamente nueva mediante TSPI_lineMakeCall, al destino de la transferencia.

Las marcas transferHeld y transferMake de la estructura de datos LINEADDRESSCAPS reportan el modelo que utiliza el proveedor de servicios.

lpCallParams

Puntero a una estructura LINECALLPARAMS que contiene parámetros de llamada que se usarán al establecer la llamada de consulta. Este parámetro se puede establecer en NULL si no se desea ningún parámetro de configuración de llamada especial (el proveedor de servicios usa valores predeterminados).

Valor devuelto

Devuelve dwRequestID o un número de error si se produce un error. El parámetro real lResult del ASYNC_COMPLETION correspondiente es cero si la función se ejecuta correctamente o un número de error si se produce un error. Los valores devueltos posibles son los siguientes:

LINEERR_INVALCALLHANDLE, LINEERR_INVALBEARERMODE, LINEERR_INVALCALLSTATE, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALCALLPARAMS, LINEERR_NOMEM, LINEERR_INVALLINESTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INUSE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_BEARERMODEUNAVAIL, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_USERUSERINFOTOOBIG.

Comentarios

El proveedor de servicios devuelve LINEERR_INVALCALLSTATE si la llamada que se va a transferir no está en un estado válido.

Esta operación configura la transferencia de la llamada especificada por hdCall. La fase de configuración de una transferencia establece una llamada de consulta para enviar la dirección del destino (la parte a la que se va a transferir) al conmutador, mientras que la llamada que se va a transferir se mantiene en espera. Esta nueva llamada se conoce como una llamada de consulta (hdConsultCall) y se puede manipular (por ejemplo, quitada) independientemente de la llamada original.

Cuando la llamada de consulta ha alcanzado el estado de llamada de dialtone , TAPI puede continuar transfiriendo la llamada llamando a la dirección de destino y realizando un seguimiento de su progreso, o manteniendo una llamada existente. La transferencia de la llamada original al destino seleccionado se completa mediante TSPI_lineCompleteTransfer.

Mientras existe la llamada de consulta, la llamada original normalmente pasa al estado onholdPendingTransfer .

La función TSPI_lineUnhold puede recuperar llamadas que tienen el estado de llamada onHoldPendingTransfer. Si esto se hace, cualquier llamada de consulta normalmente va al estado inactivo .

En entornos de telefonía que siguen los modelos de transferencia transferHeld o transferMake , este procedimiento devuelve LINEERR_OPERATIONFAILED y no asigna un identificador de llamada de consulta.

Se puede cancelar una llamada de consulta invocando TSPI_lineDrop en ella. Después de quitar una llamada de consulta, la llamada original normalmente vuelve al estado conectado .

Esta función difiere de la función TAPI correspondiente en que sigue el modelo de TSPI para comenzar la duración de una llamada. TAPI y el proveedor de servicios intercambian identificadores opacos que representan la llamada entre sí. Además, el proveedor de servicios puede realizar devoluciones de llamada para la nueva llamada antes de que vuelva de este procedimiento. En cualquier caso, el proveedor de servicios también debe tratar el identificador que devolvió como "todavía no válido" hasta después de que la coincidencia ASYNC_COMPLETION mensaje notifique que se ha realizado correctamente. En otras palabras, no debe emitir ningún mensaje LINEEVENT para la nueva llamada o incluirlo en recuentos de llamadas en mensajes o estructuras de datos de estado para la línea.