Función lineSetTerminal (tapi.h)

Artículo
03/08/2023

La función lineSetTerminal permite a una aplicación especificar la información de terminal relacionada con la línea, dirección o llamada especificada que se va a enrutar. La función lineSetTerminal se puede usar mientras las llamadas están en curso en la línea para permitir que una aplicación enrute estos eventos a distintos dispositivos según sea necesario.

Sintaxis

LONG lineSetTerminal(
  HLINE hLine,
  DWORD dwAddressID,
  HCALL hCall,
  DWORD dwSelect,
  DWORD dwTerminalModes,
  DWORD dwTerminalID,
  DWORD bEnable
);

Parámetros

hLine

Identificador de un dispositivo de línea abierta.

dwAddressID

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.

hCall

Identificador de una llamada. El estado de llamada de hCall puede ser cualquier estado, si dwSelect es CALL.

dwSelect

Indica si se solicita la configuración del terminal para la línea, la dirección o solo la llamada especificada. Si se especifica la línea o dirección, los eventos se aplican a la línea o a la propia 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 de LINECALLSELECT_.

dwTerminalModes

Clase de eventos de bajo nivel que se van a enrutar al terminal especificado. Este parámetro usa una o varias de las constantes de LINETERMMODE_.

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 de cero a uno menor que dwNumTerminals, donde dwNumTerminals y los modos de terminal que cada terminal es capaz de controlar, los devuelve lineGetDevCaps.

Estos identificadores de terminal no tienen ninguna relación con otros identificadores de dispositivo y los define el proveedor de servicios mediante funcionalidades de dispositivo.

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 hacia o desde el dispositivo terminal con el identificador igual a dwTerminalID.

Valor devuelto

Devuelve un identificador de solicitud positivo si la función se completa de forma asincrónica o un número de error negativo si se produce un error. El parámetro dwParam2 del mensaje de LINE_REPLY correspondiente es cero si la función se ejecuta correctamente o es un número de error negativo si se produce un error. Los valores devueltos posibles son:

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

Comentarios

Una aplicación puede usar esta funció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 ejemplo, la voz se puede enrutar a un dispositivo de E/S de audio (auriculares), las lámparas y los eventos de pantalla se pueden enrutar al dispositivo telefónico local, y los eventos de botón y los eventos de timbre se pueden suprimir por completo.

Se puede llamar a esta función en cualquier momento, incluso cuando una llamada está activa en el dispositivo de línea especificado. Esto 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, la aplicación primero debe deshabilitar el enrutamiento al terminal existente y, a continuación, enrutar los eventos al nuevo terminal.

Las asignaciones de identificadores de terminal se realizan mediante el proveedor de servicios de la línea. Las funcionalidades del dispositivo solo indican qué identificadores de terminal tiene disponible el proveedor de servicios. Los proveedores de servicios que no admiten este tipo de enrutamiento de eventos indicarían que no tienen ningún dispositivo terminal (dwNumTerminals en LINEDEVCAPS sería cero).

La invocación de 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 las llamadas futuras en esa línea o dirección. Una línea o dirección que tiene varias llamadas conectadas activas a la vez 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 generan necesariamente un error siempre y cuando la función se realice correctamente (los eventos especificados no se enrutan hacia o desde ese terminal).

TAPI enruta los tonos de progreso de la llamada y los mensajes a la misma ubicación que establece la función lineSetTerminal para "media". Por ejemplo, si las señales de audio van al teléfono, entonces las señales ocupadas (analógicas) o los mensajes Q.931 que indican ocupado (digital).