Função lineDial (tapi.h)

Artigo
08/26/2023

A função lineDial disca o número discável especificado na chamada especificada.

Sintaxe

LONG lineDial(
  HCALL  hCall,
  LPCSTR lpszDestAddress,
  DWORD  dwCountryCode
);

Parâmetros

hCall

Manipule para a chamada na qual um número deve ser discado. O aplicativo deve ser um proprietário da chamada. O estado de chamada de hCall pode ser qualquer estado , exceto ocioso e desconectado.

lpszDestAddress

Destino a ser discado usando o formato de número discável padrão.

dwCountryCode

Código de país ou região do destino. Isso é usado pela implementação para selecionar os protocolos de progresso da chamada para o endereço de destino. Se um valor de 0 for especificado, um protocolo de progresso de chamada padrão definido pelo provedor de serviços será usado.

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_ADDRESSBLOCKED, LINEERR_INVALPOINTER, LINEERR_DIALBILLING, LINEERR_NOMEM, LINEERR_DIALDIALTONE, LINEERR_NOTOWNER, LINEERR_DIALPROMPT, LINEERR_OPERATIONFAILED, LINEERR_DIALQUIET, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE.

Comentários

Se LINEERR_INVALADDRESS for retornado, nenhuma discagem será feita. Se LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE ou LINEERR_DIALPROMPT for retornado, nenhuma das ações executadas de outra forma por lineDial ocorreu. Por exemplo, nenhum dos endereços discáveis antes do caractere ofensivo foi discado, nenhum estado hookswitch foi alterado e assim por diante.

A função lineDial é usada para discar em uma aparência de chamada existente. Por exemplo, depois que uma chamada for configurada para transferência ou conferência, uma chamada de consulta será alocada automaticamente e a função lineDial será usada para executar a discagem desta chamada de consulta. A função lineDial pode ser invocada várias vezes no curso da discagem em vários estágios, se os recursos do dispositivo da linha permitirem. Além disso, vários endereços podem ser fornecidos em uma única cadeia de caracteres de discagem separada por CRLF. Os provedores de serviços que fornecem multiplexação inversa podem estabelecer chamadas físicas individuais com cada um dos endereços e podem retornar um único identificador de chamada para a agregação de todas as chamadas ao aplicativo. Todos os endereços usariam o mesmo código de país ou região.

A discagem é considerada concluída depois que o endereço é passado para o provedor de serviços; não depois que a chamada for finalmente conectada. Os provedores de serviços que fornecem multiplexação inversa podem permitir que vários endereços sejam fornecidos de uma só vez. O provedor de serviços envia mensagens LINE_CALLSTATE para o aplicativo para informá-lo sobre o progresso da chamada. Para anular uma tentativa de chamada enquanto uma chamada está sendo estabelecida, o aplicativo invocação deve usar lineDrop.

Um aplicativo pode definir o parâmetro lpszDestAddress da função lineDial para o endereço de uma cadeia de caracteres vazia para indicar que a discagem está concluída, mas somente se as chamadas anteriores para as funções lineMakeCall e lineDial tiverem as cadeias de caracteres especificadas por lpszDestAddress encerradas com ponto e vírgula.

A função lineDial também pode ser usada na discagem parcial. Para iniciar uma chamada usando discagem parcial, o aplicativo chama lineMakeCall e especifica uma cadeia de caracteres de discagem parcial. Uma cadeia de caracteres de discagem parcial é qualquer cadeia de caracteres de discagem terminada por ponto e vírgula. A chamada normalmente fará a transição para LINECALLSTATE_DIALING após a qual lineDial pode ser chamado para especificar mais cadeias de caracteres de discagem, cada uma terminada por ponto e vírgula. A discagem é concluída chamando lineDial com uma cadeia de caracteres de discagem que não é encerrada com um ponto e vírgula (como uma cadeia de caracteres vazia). Essa técnica permite que os aplicativos executem discagem parcial interativa com o usuário ou habilitem discagem mais sofisticada do que um TSP pode ser capaz.

Se uma cadeia de caracteres de destino nula ou uma cadeia de caracteres vazia terminada com um ponto e vírgula (";") for inserida em lineMakeCall , o aplicativo fará a transição para LINE_CALLSTATE_DIALTONE. A função lineDial pode ser chamada nesse estado para inserir uma única cadeia de caracteres de discagem ou várias cadeias de caracteres de discagem parciais, cada uma separada por ponto e vírgula. O aplicativo faz a transição para o estado LINECALLSTATE_DIALING depois que o primeiro dígito é inserido.

Nota A função lineDial só está disponível quando uma chamada está em LINECALLSTATE_DIALING ou LINE_CALLSTATE_DIALTONE. Se o DTMF for necessário enquanto uma chamada estiver conectada (LINECALLSTATE_CONNECTED), use lineGenerateDigits.