função TSPI_lineSetupConference (tspi.h)

Artigo
08/26/2023

A função TSPI_lineSetupConference configura uma chamada em conferência para a adição de terceiros.

Sintaxe

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

O identificador da solicitação assíncrona.

hdCall

O identificador para a chamada inicial que identifica a primeira parte de uma chamada em conferência. Em alguns ambientes, uma chamada deve existir para iniciar uma chamada em conferência. Em outros ambientes de telefonia, nenhuma chamada existe inicialmente e hdCall é deixado NULL. O estado de chamada do hdCall pode ser conectado.

hdLine

O identificador para o dispositivo de linha no qual originar a chamada de conferência se hdCall for NULL. O parâmetro hdLine será ignorado se hdCall não for NULL. O provedor de serviços relata qual modelo ele dá suporte por meio do sinalizador setupConfNull da estrutura de dados LINEADDRESSCAPS .

htConfCall

O identificador TAPI para a nova chamada de conferência. O provedor de serviços deve salvá-lo e usá-lo em todas as chamadas subsequentes para os eventos de relatório de procedimento LINEEVENT na nova chamada.

lphdConfCall

Um ponteiro para um HDRVCALL que representa o identificador do provedor de serviços para a chamada de conferência recém-criada. O provedor de serviços deve preencher esse local com seu identificador para a nova chamada antes que este procedimento retorne. Esse identificador será ignorado pelo TAPI se a função resultar em um erro. O estado de chamada de hdConfCall não é aplicável.

htConsultCall

O identificador TAPI para a chamada de consulta. Ao configurar uma chamada para a adição de uma nova parte, uma nova chamada temporária (chamada de consulta) é alocada automaticamente. O provedor de serviços deve salvar o htConsultCall e usá-lo em todas as chamadas subsequentes para o procedimento LINEEVENT relatando eventos na nova chamada de consulta.

lphdConsultCall

Um ponteiro para um HDRVCALL que representa o identificador do provedor de serviços para uma chamada. Ao configurar uma chamada para a adição de uma nova parte, uma nova chamada temporária (chamada de consulta) é alocada automaticamente. O provedor de serviços deve preencher esse local com seu identificador para a nova chamada de consulta antes que este procedimento retorne. Esse identificador será ignorado pelo TAPI se a função resultar em um erro. O estado de chamada de hdConsultCall não é aplicável.

dwNumParties

O número esperado de partes na teleconferência. O provedor de serviços é gratuito para fazer com esse número como quiser. Por exemplo, o provedor de serviços pode ignorá-lo ou usá-lo como uma dica para alocar a ponte de conferência de tamanho certo dentro do comutador. O TAPI não valida esse parâmetro quando essa função é chamada.

lpCallParams

Um ponteiro para uma estrutura LINECALLPARAMS que contém parâmetros de chamada a serem usados ao estabelecer a chamada de consulta. Esse parâmetro será definido como NULL se nenhum parâmetro de configuração de chamada especial for desejado e o provedor de serviços usar parâmetros padrão.

Retornar valor

Retorna dwRequestID ou um número de erro se ocorrer um erro. O parâmetro real lResult do ASYNC_COMPLETION correspondente será 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_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.

Comentários

O provedor de serviços retornará LINEERR_INVALLINEHANDLE se o identificador de linha especificado para a linha que contém a chamada em conferência for inválido. Esse erro também pode indicar que o ambiente de telefonia requer uma linha inicial para configurar uma conferência, mas um identificador de chamada não NULL foi fornecido.

O provedor de serviços retornará LINEERR_INVALCALLHANDLE se o ambiente de telefonia exigir uma chamada inicial para configurar uma conferência, mas um identificador de chamada NULL tiver sido fornecido.

TSPI_lineSetupConference fornece duas maneiras de estabelecer uma nova chamada em conferência, dependendo se uma chamada normal de duas partes é necessária para pré-existir ou não. Ao configurar uma chamada de conferência de uma chamada de duas partes existente, o parâmetro hdCall é um identificador de chamada válido que é inicialmente adicionado à chamada de conferência pela solicitação de TSPI_lineSetupConference e hdLine é ignorado. Nos comutadores em que a configuração de chamada de conferência não começa com uma chamada existente, hdCall deve ser NULL e hdLine deve ser especificado para identificar o dispositivo de linha no qual iniciar a chamada de conferência. Em ambos os casos, uma chamada de consulta é alocada para se conectar à parte que deve ser adicionada à chamada. O TAPI pode usar TSPI_lineDial para discar o endereço da outra parte.

A chamada de conferência normalmente faz a transição para o estado onHoldPendingConference , o estado de dialtone de chamada de consulta e a chamada inicial (se houver) para o estado de conferência .

Uma chamada de conferência também pode ser configurada usando uma função TSPI_lineCompleteTransfer que é resolvida em uma conferência de três vias.

O TAPI pode ser capaz de alternar entre a chamada de consulta e a chamada em conferência usando TSPI_lineSwapHold.

A função TSPI_lineUnhold pode recuperar chamadas que têm o estado de chamada onHoldPendingConference. Se isso for feito, qualquer chamada de consulta normalmente vai para o estado ocioso .

Uma chamada de consulta pode ser cancelada invocando TSPI_lineDrop nela. Ao descartar uma chamada de consulta, a chamada de conferência existente normalmente faz a transição de volta para o estado conectado . O TAPI e seus aplicativos cliente devem observar as mensagens LINE_CALLSTATE para determinar exatamente o que acontece com as chamadas. Por exemplo, se a chamada de conferência reverter para uma chamada regular de duas partes, a chamada de conferência ficará ociosa e a chamada de participante original poderá reverter para conectada.

Essa função difere da função TAPI correspondente, pois segue o modelo TSPI para iniciar o tempo de vida de uma chamada. O TAPI e o provedor de serviços trocam identificadores opacos que representam a chamada entre si. Além disso, o provedor de serviços tem permissão para fazer retornos de chamada para a nova chamada antes de retornar desse procedimento. De qualquer forma, o provedor de serviços também deve tratar o identificador retornado como "ainda não válido" até que a mensagem de ASYNC_COMPLETION correspondente reporte êxito. Em outras palavras, ele não deve emitir nenhuma mensagem LINEEVENT para a nova chamada ou incluí-la em contagens de chamadas em mensagens ou estruturas de dados status para a linha.