Função lineGenerateTone (tapi.h)

Artigo
08/26/2023

A função lineGenerateTone gera o tom de banda inband especificado sobre a chamada especificada. Invocar essa função com um zero para dwToneMode anula a geração de tom atualmente em andamento na chamada especificada. Invocar lineGenerateTone ou lineGenerateDigits enquanto a geração de tom está em andamento anula a geração atual de tom ou geração de dígitos e inicia a geração do tom ou dígitos recém-especificados.

Sintaxe

LONG lineGenerateTone(
  HCALL                    hCall,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parâmetros

hCall

Manipule para a chamada na qual um tom deve ser gerado. O aplicativo deve ser um proprietário da chamada. O estado de chamada de hCall pode ser qualquer estado.

dwToneMode

Define o tom a ser gerado. Os tons podem ser padrão ou personalizados. Um tom personalizado é composto por um conjunto de frequências arbitrárias. Um pequeno número de tons padrão é predefinido. A duração do tom é especificada com dwDuration para tons padrão e personalizados. O parâmetro dwToneMode só pode ter um bit definido. Se nenhum bit for definido (o valor 0 será passado), a geração de tom será cancelada. Esse parâmetro usa uma das constantes LINETONEMODE_.

dwDuration

Duração em milissegundos durante os quais o tom deve ser sustentado. Um valor de 0 para dwDuration usa uma duração padrão para o tom especificado. Os valores padrão são:

PERSONALIZADO: o tom é mantido até ser desligado, geralmente por interação do usuário ou um tempo limite do equipamento.

RINGBACK: o tom é mantido até ser desligado, geralmente por interação do usuário ou um tempo limite do equipamento.

OCUPADO: o tom é mantido até ser desligado, geralmente por interação do usuário ou um tempo limite do equipamento.

BEEP: o tom é mantido até ser desligado, geralmente por interação do usuário ou um tempo limite do equipamento.

COBRANÇA: corrigido (ciclo único).

dwNumTones

Número de entradas na matriz lpTones . Esse parâmetro será ignorado se dwToneMode não for igual a CUSTOM.

lpTones

Ponteiro para uma matriz LINEGENERATETONE que especifica os componentes do tom. Esse parâmetro é ignorado para tons padrão LINETONEMODE_ Constantes , como LINETONEMODE_BUSY. Se lpTones for um tom de multifrequência, os vários tons serão reproduzidos simultaneamente.

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_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED, LINEERR_NOMEM.

Comentários

A função lineGenerateTone é considerada concluída com êxito quando a geração de tom foi iniciada com êxito, não quando a geração do tom é concluída. A função permite a geração de banda de vários tons predefinidos, como ringback, tons ocupados e bipe. Ele também permite a fabricação de tons personalizados especificando suas frequências de componente, cadência e volume. Como esses tons são gerados como tons de banda, a chamada normalmente teria que estar no estado conectado para que a geração de tom seja eficaz. Quando a geração do tom é concluída ou quando a geração de tom é cancelada, uma mensagem LINE_GENERATE é 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. Isso implica que, se a geração de tom estiver atualmente em andamento em uma chamada, invocar lineGenerateDigits cancelará a geração de tom.

Se o valor de erro LINEERR_INVALPOINTER for retornado, o parâmetro lpTones especificado será inválido ou o valor especificado pelo parâmetro dwNumTones será muito grande.