função TSPI_lineMonitorMedia (tspi.h)

Artigo
03/13/2024

A função TSPI_lineMonitorMedia habilita e desabilita a detecção de tipos de mídia na chamada especificada. Quando um tipo de mídia é detectado, uma mensagem LINE_MONITORMEDIA é enviada ao TAPI.

Sintaxe

LONG TSPIAPI TSPI_lineMonitorMedia(
  HDRVCALL hdCall,
  DWORD    dwMediaModes
);

Parâmetros

hdCall

O identificador para a chamada para a qual o monitoramento de mídia deve ser definido. O estado de chamada do hdCall pode ser qualquer estado, exceto ocioso.

dwMediaModes

Os tipos de mídia a serem monitorados. O parâmetro dwMediaModes pode ter uma das constantes LINEMEDIAMODE_.

Um valor 0 cancela todo o monitoramento de tipo de mídia.

Retornar valor

Retornará zero se a função for bem-sucedida ou um número de erro se ocorrer um erro. Os possíveis valores retornados são os seguintes:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM.

Comentários

O provedor de serviços retornará LINEERR_INVALMEDIAMODE se a lista de tipos de mídia a serem monitorados contiver informações inválidas.

Essa função retorna zero (êxito) quando o monitoramento de tipo de mídia foi iniciado corretamente, não quando o monitoramento de tipo de mídia é encerrado. O monitoramento de mídia para um determinado tipo de mídia permanece em vigor até que seja explicitamente desabilitado chamando TSPI_lineMonitorMedia com um parâmetro dwMediaModes com o tipo de mídia definido como zero ou até que a chamada faça a transição para ocioso.

TSPI_lineMonitorMedia é principalmente um mecanismo de relatório de eventos. O tipo de mídia de uma chamada, conforme indicado em LINECALLINFO, não é afetado pela detecção do tipo de mídia pelo provedor de serviços. Somente o TAPI ou um aplicativo cliente pode alterar o tipo de mídia indicado de uma chamada usando TSPI_lineSetMediaMode. O uso real de um tipo de mídia específico ocorre por meio de APIs de fluxo de mídia separadas (como Comm ou WAVE).

O monitoramento de mídia padrão executado pelo provedor de serviços para uma nova aparência de chamada corresponde à união de todos os tipos de mídia especificados por TSPI_lineSetDefaultMediaDetection. Logo após a criação de uma nova chamada, a TAPI normalmente chama TSPI_lineMonitorMedia para reduzir o conjunto de tipos de mídia detectados e relatados para essa chamada para a união de todos os tipos de mídia desejados pelos aplicativos cliente da chamada.

O provedor de serviços deve cancelar o monitoramento de mídia quando uma chamada fica ociosa. O TAPI deve calcular a união dos tipos de mídia desejados por todos os clientes e passar o resultado para essa função. O provedor de serviços usa o conjunto passado para essa função pelo TAPI.

Embora essa função possa ser invocada em qualquer estado de chamada, o tipo de mídia de uma chamada normalmente só pode ser detectado enquanto a chamada está em determinados estados de chamada. Esses estados podem ser específicos do dispositivo. Por exemplo, no ISDN, uma mensagem pode indicar o tipo de mídia do fluxo de mídia antes que o fluxo de mídia exista. Da mesma forma, toques distintos ou as informações de ID chamadas sobre a chamada podem ser usadas para identificar o tipo de mídia de uma chamada. Caso contrário, a chamada pode ter que ser atendida (chamada no estado conectado ) para permitir que um provedor de serviços determine o tipo de mídia da chamada filtrando o fluxo de mídia. Como a filtragem do fluxo de mídia de uma chamada implica uma sobrecarga computacional, o TAPI normalmente usa esse procedimento para desabilitar o monitoramento de mídia quando não é necessário.

Como a detecção do modo de mídia habilitada por TSPI_lineMonitorMedia é implementada como uma operação somente leitura do fluxo de mídia da chamada, ela não é disruptiva. Nenhum sinal é enviado na linha como resultado da configuração TSPI_lineMonitorMedia.

Em relação ao tipo de mídia passado, o TAPI garante que não há nenhum conjunto de bits reservados. O provedor de serviços deve executar quaisquer verificações de validade adicionais nos tipos de mídia, como verificar se algum tipo de mídia tem suporte de fato pelo provedor de serviços.