Função lineGenerateDigits (tapi.h)

Artigo
08/26/2023

A função lineGenerateDigits inicia a geração dos dígitos especificados na chamada especificada como tons de banda usando o modo de sinalização especificado. Chamar essa função com um valor NULL para lpszDigits anula qualquer geração de dígito atualmente em andamento. Invocar lineGenerateDigits ou lineGenerateTone enquanto a geração de dígitos está em andamento anula a geração atual de dígitos ou a geração de tom e inicia a geração dos dígitos ou tom especificados mais recentemente.

Sintaxe

LONG lineGenerateDigits(
  HCALL  hCall,
  DWORD  dwDigitMode,
  LPCSTR lpszDigits,
  DWORD  dwDuration
);

Parâmetros

hCall

Manipule para a chamada. O aplicativo deve ser um proprietário da chamada. O estado de chamada de hCall pode ser qualquer estado. O TAPI não impõe nenhum requisito de callstate, no entanto, alguns Provedores de Serviços tapi podem exigir que o hCall esteja no estado LINECALLSTATE_CONNECTED.

dwDigitMode

Formato a ser usado para sinalizar esses dígitos. Lembre-se de que dwDigitMode só pode ter um único sinalizador definido. Esse parâmetro usa uma das constantes LINEDIGITMODE_.

lpszDigits

Ponteiro para um buffer de caracteres terminado em nulo que contém os dígitos a serem gerados. Caracteres válidos são aqueles especificados para as constantes LINEDIGITMODE_ fornecidas em dwDigitModes.

Além disso, a vírgula (,) também é um caractere válido. Uma vírgula injeta um atraso extra entre a sinalização dos dígitos anterior e próximo separados. A duração dessa pausa é definida pela configuração e os recursos do dispositivo de linha indicam essa duração. Várias vírgulas podem ser usadas para injetar pausas mais longas. Dígitos inválidos são ignorados durante a geração, em vez de serem relatados como erros.

A exclamação (!) é um caractere válido. Esse caractere causa uma operação "hookflash", conforme descrito para endereços discáveis.

dwDuration

A duração em milissegundos de dígitos DTMF e o espaçamento entre dígitos de pulso e DTMF. Um valor 0 usa um valor padrão. O parâmetro dwDuration deve estar dentro do intervalo especificado por MinDialParams e MaxDialParams em LINEDEVCAPS. Se estiver fora do intervalo, o valor real será definido como o valor mais próximo no intervalo.

Retornar valor

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

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALPOINTER, LINEERR_RESOURCEUNAVAIL, LINEERR_NOMEM, LINEERR_UNINITIALIZED.

Comentários

A função lineGenerateDigits é considerada concluída com êxito quando a geração de dígitos foi iniciada com êxito, não quando todos os dígitos foram gerados. Em contraste com lineDial, que disca dígitos de forma dependente de rede, lineGenerateDigits garante produzir os dígitos como tons de banda inband sobre o canal de voz usando pulsos de discagem DTMF ou hookswitch ao usar pulsos de discagem. A função lineGenerateDigits geralmente não é adequada para fazer chamadas ou discagem. Destina-se à sinalização de ponta a ponta em uma chamada estabelecida.

Depois que todos os dígitos em lpszDigits tiverem sido gerados ou após a geração de dígitos ter sido anulada ou cancelada, uma mensagem LINE_GENERATE será enviada ao aplicativo.

Apenas uma solicitação de geração de banda (geração de tom ou geração de dígitos) tem permissão para estar em andamento por chamada em todos os aplicativos que são proprietários da chamada. A geração de dígitos em uma chamada é cancelada iniciando outra solicitação de geração de dígito ou uma solicitação de geração de tom. Para cancelar a geração de dígitos atual, o aplicativo pode invocar lineGenerateDigits e especificar NULL para o parâmetro lpszDigits .

Dependendo do provedor de serviços e do hardware, o aplicativo pode monitorar os dígitos gerados por ele mesmo. Se isso não for desejado, o aplicativo poderá desabilitar o monitoramento de dígitos ao gerar dígitos.