função TSPI_lineMakeCall (tspi.h)

Artigo
08/26/2023

A função TSPI_lineMakeCall coloca uma chamada na linha especificada para o endereço de destino especificado. Opcionalmente, os parâmetros de chamada poderão ser especificados se qualquer coisa, exceto os parâmetros de configuração de chamada padrão, forem solicitados.

Sintaxe

LONG TSPIAPI TSPI_lineMakeCall(
  DRV_REQUESTID          dwRequestID,
  HDRVLINE               hdLine,
  HTAPICALL              htCall,
  LPHDRVCALL             lphdCall,
  LPCWSTR                lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parâmetros

dwRequestID

O identificador da solicitação assíncrona.

hdLine

O identificador para a linha na qual a nova chamada deve ser originada.

htCall

O identificador TAPI para a nova chamada. 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 chamada.

lphdCall

Um ponteiro para um identificador de chamada. O provedor de serviços deve preencher esse local com seu identificador para a chamada antes que este procedimento retorne. Esse identificador será ignorado pelo TAPI se a função resultar em um erro.

lpszDestAddress

Ponteiro para uma cadeia de caracteres Unicode terminada em nulo que especifica o endereço de destino. Isso segue o formato de número discável padrão. Esse ponteiro pode ser especificado como NULL para endereços não discados (como em um telefone quente, que sempre se conecta automaticamente a um número predefinido) ou quando todas as discagem são executadas usando TSPI_lineDial. No último caso, TSPI_lineMakeCall aloca uma aparência de chamada disponível que normalmente permaneceria no estado dialtone até que a discagem comece. Os provedores de serviços que têm funcionalidades de multiplexação inversas podem permitir que um aplicativo especifique vários endereços ao mesmo tempo.

dwCountryCode

O código do país ou região da parte chamada. Se um valor de 0 for especificado, um padrão será usado pela implementação.

lpCallParams

Um ponteiro para uma estrutura LINECALLPARAMS . Essa estrutura permite que o TAPI especifique como deseja que a chamada seja configurada. Se NULL for especificado, uma chamada de voz padrão de 3,1kHz será estabelecida e um endereço de origem arbitrária na linha será selecionado. Essa estrutura seleciona elementos como o modo de portador da chamada, a taxa de dados, o tipo de mídia esperado, o endereço de origem, o bloqueio de informações de ID do chamador e os parâmetros de discagem.

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_ADDRESSBLOCKED, LINEERR_INVALLINESTATE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_DIALBILLING, LINEERR_INVALADDRESS, LINEERR_DIALQUIET, LINEERR_INVALADDRESSID, LINEERR_DIALDIALTONE, LINEERR_INVALCALLPARAMS, LINEERR_DIALPROMPT, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_ INVALCOUNTRYCODE, LINEERR_RATEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_USERUSERINFOTOOBIG.

Comentários

O provedor de serviços retornará LINEERR_INVALLINESTATE se a linha não estiver atualmente em um estado no qual essa operação pode ser executada. Uma lista de operações válidas no momento pode ser encontrada no membro dwLineFeatures (do tipo LINEFEATURE) na estrutura LINEDEVSTATUS . (Chamar TSPI_lineGetLineDevStatus atualiza as informações em LINEDEVSTATUS.)

Se o provedor de serviços retornar LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE ou LINEERR_DIALPROMPT, ele não deverá executar nenhuma das ações executadas de outra forma por TSPI_lineMakeCall. Por exemplo, sem discagem parcial e sem offhook. Isso ocorre porque o provedor de serviços deve verificar previamente o número de caracteres sem suporte primeiro.

Depois que TSPI_lineMakeCall retorna uma mensagem de retorno de chamada de resposta SUCCESS para o aplicativo, o provedor de serviços deve enviar mensagens LINE_CALLSTATE para o lpfnEventProc passado em TSPI_lineOpen para notificar o TAPI sobre o progresso da chamada. Uma sequência relatada típica pode ser o tom de discagem, discagem, continuação, ringback e conectado; O primeiro estado relatado não é necessariamente LINECALLSTATE_DIALTONE. O provedor de serviços escolhe quantos desses estados são relatados. É recomendável que o maior número possível seja enviado, para que os aplicativos possam tomar as ações apropriadas.

Inicialmente, o provedor de serviços faz o monitoramento de mídia na nova chamada para pelo menos o conjunto de tipos de mídia que foram monitorados na linha.

Se a cadeia de caracteres de discagem for NULL, o provedor de serviços usará a linha para o estado dialtone (para um provedor de serviços baseado em comm, isso envolverá ATD) e enviará uma mensagem de estado de chamada indicando LINECALLSTATE_DIALTONE.

Se a cadeia de caracteres de discagem terminar em ';' (ponto e vírgula), o provedor de serviço disca o número parcial e envia a mensagem LINECALLSTATE_DIALING. Essa chamada é concluída por chamadas para TSPI_lineDial.

Se a cadeia de caracteres de discagem contiver caracteres (W, @, $, ?) que não são compatíveis com o provedor de serviços, o provedor de serviços deverá verificar a cadeia de caracteres de discagem e retornar (de forma síncrona) um erro correspondente ao primeiro caractere inválido.

Se o sinalizador LINECALLPARAMFLAGS_IDLE estiver definido, o provedor de serviços deverá marcar a status de linha atual (o equivalente a sair do gancho e detectar o tom de discagem). Se esse sinalizador IDLE estiver definido e não houver nenhum tom de discagem, a função falhará com o erro LINEERR_CALLUNAVAIL. Se o sinalizador IDLE não estiver definido ou houver um tom de discagem, a discagem poderá continuar.

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. 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.