TSPI_lineSetupConference función (tspi.h)

Artículo
08/26/2023

La función TSPI_lineSetupConference configura una llamada de conferencia para la adición del tercero.

Sintaxis

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

Parámetros

dwRequestID

Identificador de la solicitud asincrónica.

hdCall

Identificador de la llamada inicial que identifica a la primera parte de una llamada de conferencia. En algunos entornos, debe existir una llamada para iniciar una llamada de conferencia. En otros entornos de telefonía, inicialmente no existe ninguna llamada y hdCall se deja NULL. El estado de llamada de hdCall se puede conectar.

hdLine

Identificador del dispositivo de línea en el que se origina la llamada de conferencia si hdCall es NULL. El parámetro hdLine se omite si hdCall no es NULL. El proveedor de servicios notifica qué modelo admite a través de la marca setupConfNull de la estructura de datos LINEADDRESSCAPS .

htConfCall

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

lphdConfCall

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

htConsultCall

El TAPI se encarga de la llamada de consulta. Al configurar una llamada para la adición de una nueva entidad, se asigna automáticamente una nueva llamada temporal (llamada de consulta). El proveedor de servicios debe guardar la llamada htConsultCall y usarla 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 una llamada. Al configurar una llamada para la adición de una nueva entidad, se asigna automáticamente una nueva llamada temporal (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.

dwNumParties

El número esperado de partes en la convocatoria de conferencia. El proveedor de servicios es libre de hacer con este número, ya que por favor. Por ejemplo, el proveedor de servicios puede omitirlo o usarlo como sugerencia para asignar el puente de conferencia de tamaño correcto dentro del conmutador. TAPI no valida este parámetro cuando se llama a esta función.

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 establece en NULL si no se desea ningún parámetro de configuración de llamada especial y el proveedor de servicios usa parámetros 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_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.

Comentarios

El proveedor de servicios devuelve LINEERR_INVALLINEHANDLE si el identificador de línea especificado para la línea que contiene la llamada de conferencia no es válido. Este error también puede indicar que el entorno de telefonía requiere una línea inicial para configurar una conferencia, pero se proporcionó un identificador de llamada que no es NULL .

El proveedor de servicios devuelve LINEERR_INVALCALLHANDLE si el entorno de telefonía requiere una llamada inicial para configurar una conferencia, pero se proporcionó un identificador de llamada NULL en su lugar.

TSPI_lineSetupConference proporciona dos maneras de establecer una nueva llamada de conferencia, en función de si se requiere una llamada normal de dos partes para existir previamente o no. Al configurar una llamada de conferencia desde una llamada de dos partes existente, el parámetro hdCall es un identificador de llamada válido que se agrega inicialmente a la llamada de conferencia mediante la solicitud de TSPI_lineSetupConference y se omite hdLine . En los conmutadores en los que la configuración de la llamada de conferencia no comienza con una llamada existente, hdCall debe ser NULL y hdLine debe especificarse para identificar el dispositivo de línea en el que iniciar la llamada de conferencia. En cualquier caso, se asigna una llamada de consulta para conectarse a la parte que se va a agregar a la llamada. TAPI puede usar TSPI_lineDial para marcar la dirección de la otra parte.

La llamada de conferencia normalmente pasa al estado onHoldPendingConference , el estado de llamada de llamada de consulta dialtone y la llamada inicial (si la hay) al estado con conferencia .

También se puede configurar una llamada de conferencia mediante una función de TSPI_lineCompleteTransfer que se resuelve en una conferencia triple.

TAPI puede alternar entre la llamada de consulta y la llamada de conferencia mediante TSPI_lineSwapHold.

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

Se puede cancelar una llamada de consulta invocando TSPI_lineDrop en ella. Al quitar una llamada de consulta, la llamada de conferencia existente normalmente vuelve al estado conectado . TAPI y sus aplicaciones cliente deben observar los mensajes de LINE_CALLSTATE para determinar exactamente lo que sucede con las llamadas. Por ejemplo, si la llamada de conferencia vuelve a una llamada periódica de dos partes, la llamada de conferencia se vuelve inactiva y la llamada de participante original puede revertirse a conectada.

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.