Função lineSetTerminal (tapi.h)

Artigo
08/26/2023

A função lineSetTerminal permite que um aplicativo especifique quais informações de terminal relacionadas à linha, endereço ou chamada especificadas devem ser roteadas. A função lineSetTerminal pode ser usada enquanto as chamadas estão em andamento na linha para permitir que um aplicativo encaminhe esses eventos para diferentes dispositivos conforme necessário.

Sintaxe

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

Parâmetros

hLine

Manipule para um dispositivo de linha aberta.

dwAddressID

Endereço no dispositivo de linha aberta especificado. Um identificador de endereço está permanentemente associado a um endereço; o identificador permanece constante entre as atualizações do sistema operacional.

hCall

Manipule para uma chamada. O estado de chamada de hCall pode ser qualquer estado, se dwSelect for CALL.

dwSelect

Se a configuração do terminal é solicitada para a linha, o endereço ou apenas a chamada especificada. Se linha ou endereço for especificado, os eventos se aplicarão à própria linha ou endereço ou servirão como uma configuração inicial padrão para todas as novas chamadas na linha ou endereço. Esse parâmetro usa uma das constantes LINECALLSELECT_.

dwTerminalModes

Classe de eventos de baixo nível a serem roteado para o terminal especificado. Esse parâmetro usa uma ou mais constantes de LINETERMMODE_.

dwTerminalID

Identificador de dispositivo do dispositivo de terminal para onde os eventos determinados devem ser roteado. Os identificadores de terminal são pequenos inteiros no intervalo de zero a um a menos que dwNumTerminals, em que dwNumTerminals e os modos de terminal que cada terminal é capaz de manipular, são retornados por lineGetDevCaps.

Esses identificadores de terminal não têm relação com outros identificadores de dispositivo e são definidos pelo provedor de serviços usando recursos de dispositivo.

bEnable

Se TRUE, dwTerminalID será válido e as classes de evento especificadas serão roteadas para ou desse terminal. Se FALSE, esses eventos não serão roteados de ou para o dispositivo de terminal com identificador igual a dwTerminalID.

Valor retornado

Retorna um identificador de solicitação positivo se a função for concluída de forma assíncrona ou um número de erro negativo se ocorrer um erro. O parâmetro dwParam2 da mensagem de LINE_REPLY correspondente será zero se a função for bem-sucedida ou se for um número de erro negativo se ocorrer um erro. Os possíveis valores retornados são:

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

Comentários

Um aplicativo pode usar essa função para rotear determinadas classes de eventos de linha de baixo nível para o dispositivo de terminal especificado ou para suprimir o roteamento desses eventos. Por exemplo, a voz pode ser roteada para um dispositivo de E/S de áudio (headset), lâmpadas e eventos de exibição podem ser roteados para o dispositivo de telefone local, e eventos de botão e eventos de toque podem ser suprimidos completamente.

Essa função pode ser chamada a qualquer momento, mesmo quando uma chamada está ativa no dispositivo de linha especificado. Isso permite que um usuário alterne do uso do telefone local definido para outro dispositivo de E/S de áudio. Essa função pode ser chamada várias vezes para rotear os mesmos eventos para vários terminais simultaneamente. Para redirecionar eventos para um terminal diferente, o aplicativo deve primeiro desabilitar o roteamento para o terminal existente e, em seguida, rotear os eventos para o novo terminal.

As atribuições de identificador de terminal são feitas pelo provedor de serviços da linha. Os recursos do dispositivo indicam apenas quais identificadores de terminal o provedor de serviços tem disponíveis. Provedores de serviços que não dão suporte a esse tipo de roteamento de eventos indicam que não têm dispositivos de terminal (dwNumTerminals em LINEDEVCAPS seria zero).

Invocar lineSetTerminal em uma linha ou endereço afeta todas as chamadas existentes nessa linha ou endereço, mas não afeta chamadas em outros endereços. Ele também define o padrão para chamadas futuras nessa linha ou endereço. Uma linha ou endereço que tenha várias chamadas conectadas ativas ao mesmo tempo pode ter um roteamento diferente em vigor para cada chamada.

Desabilitar o roteamento de eventos de baixo nível para um terminal quando esses eventos não são roteados no momento para ou desse terminal não gera necessariamente um erro desde que a função seja bem-sucedida (os eventos especificados não são roteados para ou desse terminal).

O TAPI roteia os tons de progresso das chamadas e as mensagens para o mesmo local definido pela função lineSetTerminal para "media". Por exemplo, se os sinais de áudio estiverem indo para o telefone, os sinais ocupados também serão (analógicos) ou mensagens Q.931 indicando ocupado (digital).