função TSPI_lineSetupTransfer (tspi.h)

Artigo
03/03/2024

A função TSPI_lineSetupTransfer inicia uma transferência da chamada especificada por hdCall. Estabelece uma chamada de consulta, lphdConsultCall, na qual a parte pode ser discada que pode se tornar o destino da transferência.

Sintaxe

LONG TSPIAPI TSPI_lineSetupTransfer(
  DRV_REQUESTID          dwRequestID,
  HDRVCALL               hdCall,
  HTAPICALL              htConsultCall,
  LPHDRVCALL             lphdConsultCall,
  LPLINECALLPARAMS const lpCallParams
);

Parâmetros

dwRequestID

O identificador da solicitação assíncrona.

hdCall

O identificador para a chamada a ser transferida. O estado de chamada do hdCall pode ser conectado.

htConsultCall

O identificador TAPI para a nova chamada de consulta temporária. O provedor de serviços deve salvá-lo 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 a nova chamada de consulta. 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.

Ao configurar uma chamada para transferência, outra chamada (uma chamada de consulta) é alocada automaticamente para permitir que o aplicativo (por meio do TAPI) disque o endereço (usando TSPI_lineDial) da parte para onde a chamada deve ser transferida. A parte de origem pode continuar uma conversa sobre esta chamada de consulta antes de concluir a transferência.

Esse procedimento de transferência pode não ser válido para alguns dispositivos de linha. Em vez de chamar esse procedimento, o TAPI pode precisar desocupar uma chamada mantida existente (usando TSPI_lineUnhold) para identificar o destino da transferência. Em comutadores que dão suporte à transferência de chamadas entre endereços, a chamada de consulta pode existir em um endereço diferente da chamada a ser transferida. Também pode ser necessário configurar a chamada de consulta como uma chamada totalmente nova usando TSPI_lineMakeCall, para o destino da transferência.

Os sinalizadores transferHeld e transferMake na estrutura de dados LINEADDRESSCAPS relatam qual modelo o provedor de serviços usa.

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 poderá ser definido como NULL se nenhum parâmetro de configuração de chamada especial for desejado (o provedor de serviços usa padrões).

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 valores retornados possíveis são os seguintes:

LINEERR_INVALCALLHANDLE, LINEERR_INVALBEARERMODE, LINEERR_INVALCALLSTATE, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALCALLPARAMS, LINEERR_NOMEM, LINEERR_INVALLINESTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_OPERATIONFAILED, LINEERR_INUSE, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_BEARERMODEUNAVAIL, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_USERUSERINFOTOOBIG.

Comentários

O provedor de serviços retornará LINEERR_INVALCALLSTATE se a chamada a ser transferida não estiver em um estado válido.

Essa operação configura a transferência da chamada especificada por hdCall. A fase de configuração de uma transferência estabelece uma chamada de consulta para enviar o endereço do destino (a parte a ser transferida) para o comutador, enquanto a chamada a ser transferida é mantida em espera. Essa nova chamada é conhecida como chamada de consulta (hdConsultCall) e pode ser manipulada (por exemplo, descartada) independentemente da chamada original.

Quando a chamada de consulta atingir o estado de chamada dialtone , a TAPI poderá continuar transferindo a chamada discando o endereço de destino e acompanhando seu progresso ou desativando uma chamada existente. A transferência da chamada original para o destino selecionado é concluída usando TSPI_lineCompleteTransfer.

Embora a chamada de consulta exista, a chamada original normalmente faz a transição para o estado onholdPendingTransfer .

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

Em ambientes de telefonia que seguem os modelos de transferência transferHeld ou transferMake , este procedimento retorna LINEERR_OPERATIONFAILED e não aloca um identificador de chamada de consulta.

Uma chamada de consulta pode ser cancelada invocando TSPI_lineDrop nela. Depois de cancelar uma chamada de consulta, a chamada original normalmente faz a transição de volta para o estado conectado .

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é depois que a mensagem de ASYNC_COMPLETION correspondente relatar ê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 status estruturas de dados para a linha.