función TSPI_lineSetTerminal (tspi.h)

Artículo
08/26/2023

La función TSPI_lineSetTerminal permite a TAPI especificar a qué información de terminal relacionada con la línea, la dirección o la llamada especificadas se enrutarán. Esta operación se puede usar mientras las llamadas están en curso en la línea para permitir que los eventos se enruten a diferentes dispositivos según sea necesario.

Sintaxis

LONG TSPIAPI TSPI_lineSetTerminal(
  DRV_REQUESTID dwRequestID,
  HDRVLINE      hdLine,
  DWORD         dwAddressID,
  HDRVCALL      hdCall,
  DWORD         dwSelect,
  DWORD         dwTerminalModes,
  DWORD         dwTerminalID,
  DWORD         bEnable
);

Parámetros

dwRequestID

Identificador de la solicitud asincrónica.

hdLine

Identificador de una línea.

dwAddressID

Una dirección en el dispositivo de línea abierta especificado. Un identificador de dirección está asociado permanentemente a una dirección; el identificador permanece constante en las actualizaciones del sistema operativo. TAPI no valida este parámetro cuando se llama a esta función.

hdCall

Identificador de una llamada. El estado de llamada puede ser cualquier estado (si dwSelect es LINECALLSELECT_CALL).

dwSelect

Especifica si se solicita la configuración del terminal para la línea, la dirección o simplemente la llamada especificada. Si se especifica la línea o la dirección, los eventos se aplican a la propia línea o dirección o sirven como una configuración inicial predeterminada para todas las llamadas nuevas en la línea o dirección. Este parámetro usa una de las constantes LINECALLSELECT_.

dwTerminalModes

Las clases de eventos de bajo nivel que se enrutarán al terminal especificado. Use una de las constantes de LINETERMMODE_ para este parámetro.

dwTerminalID

Identificador de dispositivo del dispositivo de terminal en el que se enrutarán los eventos especificados. Los identificadores de terminal son pequeños enteros en el intervalo comprendido entre 0 y dwNumTerminals menos uno, donde dwNumTerminals y los modos de terminal que cada terminal es capaz de controlar se indica mediante el proveedor de servicios en LINEDEVCAPS.

Nota Estos identificadores de terminal no tienen ninguna relación con otros identificadores de dispositivo y los define el proveedor de servicios a través de las funcionalidades del dispositivo. TAPI no valida este parámetro cuando se llama a esta función.

bEnable

Si es TRUE, dwTerminalID es válido y las clases de eventos especificadas se enrutan a o desde ese terminal. Si es FALSE, estos eventos no se enrutan a ni desde dwTerminalID. TAPI no valida este parámetro cuando se llama a esta función.

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 realiza correctamente o si se produce un error. Los valores devueltos posibles son los siguientes:

LINEERR_INVALLINEHANDLE, LINEERR_INVALTERMINALID, LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTERMINALMODE, LINEERR_OPERATIONFAILED.

Comentarios

El proveedor de servicios devuelve LINEERR_RESOURCEUNAVAIL si no se puede completar la operación debido a la sobrecarga de recursos o si se establecen demasiados terminales, debido a limitaciones de hardware o a las limitaciones del proveedor de servicios o del controlador de dispositivo.

TAPI puede usar esta operación para enrutar determinadas clases de eventos de línea de bajo nivel al dispositivo terminal especificado, o para suprimir el enrutamiento de estos eventos por completo. Por ejemplo, la voz se puede enrutar a un dispositivo de E/S de audio independiente (auriculares), las lámparas y los eventos de visualización se pueden enrutar al dispositivo telefónico local, y los eventos de botones y eventos de timbre se pueden suprimir por completo.

Los tonos de progreso y/o mensajes de llamada se enrutan al mismo lugar que los medios. Por ejemplo, si las señales de audio van al teléfono, entonces hay señales ocupadas (analógica) o mensajes Q.931 que indican ocupado (digital).

El proveedor de servicios debe determinar si las combinaciones de dwSelect y dwTerminalModes son legales.

Esta operación se puede llamar en cualquier momento, incluso cuando una llamada está activa en el dispositivo de línea determinado. Por ejemplo, permite que un usuario cambie del uso del teléfono local establecido en otro dispositivo de E/S de audio.

Se puede llamar a esta función varias veces para enrutar los mismos eventos a varios terminales simultáneamente. Para volver a enrutar eventos a un terminal diferente, TAPI recomienda que la aplicación deshabilite primero el enrutamiento al terminal existente y, a continuación, enrute los eventos al nuevo terminal. Sin embargo, el proveedor de servicios debe hacer todo lo posible para dar cabida a las solicitudes de la aplicación en cualquier secuencia.

El proveedor de servicios realiza asignaciones de identificadores de terminal y LINEDEVCAPS indica qué identificadores de terminal tiene disponibles el proveedor de servicios. Los proveedores de servicios que no admiten este tipo de enrutamiento de eventos indican que no tienen ningún dispositivo terminal (dwNumTerminals en LINEDEVCAPS está establecido en cero).

LineSetTerminal en una línea o dirección afecta a todas las llamadas existentes en esa línea o dirección, pero no afecta a las llamadas en otras direcciones. También establece el valor predeterminado para futuras llamadas en esa línea o dirección. Una línea o dirección que tiene varias llamadas conectadas activas en cualquier momento puede tener un enrutamiento diferente en vigor para cada llamada.

Deshabilitar el enrutamiento de eventos de bajo nivel a un terminal cuando estos eventos no se enrutan actualmente a o desde ese terminal no es necesario generar un error siempre y cuando la función se realice correctamente, los eventos especificados no se enrutan a ese terminal ni desde ese terminal.