função TSPI_lineGenerateTone (tspi.h)

Artigo
08/26/2023

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

Sintaxe

LONG TSPIAPI TSPI_lineGenerateTone(
  HDRVCALL                 hdCall,
  DWORD                    dwEndToEndID,
  DWORD                    dwToneMode,
  DWORD                    dwDuration,
  DWORD                    dwNumTones,
  LPLINEGENERATETONE const lpTones
);

Parâmetros

hdCall

O identificador do provedor de serviços para a chamada na qual a geração de tom deve ser executada. O estado de chamada do hdCall pode ser qualquer estado, exceto ocioso.

dwEndToEndID

Um identificador exclusivo e não interpretado da solicitação para todo o seu tempo de vida, ou seja, até que a mensagem de LINE_GENERATE correspondente seja enviada. O provedor de serviços inclui esse identificador como um dos parâmetros na mensagem.

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 por dwDuration para tons padrão e personalizados. Se dwToneMode estiver definido como zero, qualquer geração de dígito ou tom em andamento será cancelada. Esse parâmetro usa uma e apenas uma das constantes LINETONEMODE_.

dwDuration

A duração em milissegundos durante a qual o tom é sustentado. Um valor de 0 para dwDuration usa uma duração padrão para o tom especificado. Os valores padrão são:

PERSONALIZADO: infinito

RINGBACK: infinito

OCUPADO: infinito

BEEP: infinito

COBRANÇA: fixa (ciclo único)

Esse parâmetro não é validado pelo TAPI quando essa função é chamada.

dwNumTones

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

lpTones

Um ponteiro para uma matriz LINEGENERATETONE que especifica os componentes do tom. Esse parâmetro é ignorado para tons não personalizados. Se lpTones for um tom de multifrequência, os vários tons serão reproduzidos simultaneamente.

Retornar valor

Retornará 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_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTONEMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL, LINEERR_RESOURCEUNAVAIL.

Comentários

TSPI_lineGenerateTone retorna zero (êxito) quando a geração de tom é iniciada com êxito; não quando a geração do tom for 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, se isso for compatível com o provedor de serviços. 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 de tom é concluída ou quando a geração de tom é cancelada, uma mensagem LINE_GENERATE é enviada ao TAPI.

Nota 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. Isso implica que, se a geração de tom estiver atualmente em andamento em uma chamada, invocar TSPI_lineGenerateDigits ou TSPI_lineGenerateTone cancelará a geração de tom. O provedor de serviços deve encerrar qualquer geração de tom em andamento quando uma função TSPI_lineGenerateDigits ou TSPI_lineGenerateTone subsequente for invocada.

A função correspondente no nível TAPI não inclui o parâmetro formal dwEndToEndID. Nesse nível, não há marcação de ponta a ponta. O TAPI usa a marcação de ponta a ponta no nível do TSPI para distinguir uma TSPI_lineGenerateTone solicitação de outra.