функция TSPI_lineGenerateTone (tspi.h)

Статья
08/26/2023

Функция TSPI_lineGenerateTone создает заданный тон inband по указанному вызову. Вызов этой функции с нулевым значением для dwToneMode прерывает любое создание звукового сигнала, в настоящее время выполняется при указанном вызове. Вызов TSPI_lineGenerateTone или TSPI_lineGenerateDigits во время создания тона прерывает текущее поколение тона или генерацию цифр и инициирует создание только что указанного тона или цифр.

Синтаксис

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

Параметры

hdCall

Дескриптор поставщика услуг для вызова, для которого будет выполнено создание звукового сигнала. Состояние вызова hdCall может быть любым, кроме состояния простоя.

dwEndToEndID

Уникальный неинтерпретированный идентификатор запроса в течение всего времени его существования, то есть до отправки соответствующего LINE_GENERATE сообщения. Поставщик услуг включает этот идентификатор в качестве одного из параметров в сообщении.

dwToneMode

Определяет тон для создания. Тоны могут быть стандартными или пользовательскими. Пользовательский тон состоит из набора произвольных частот. Предопределено небольшое количество стандартных тонов. Длительность тона определяется dwDuration как для стандартных, так и для пользовательских тонов. Если параметру dwToneMode присвоено значение 0, любая выполняемая генерация цифр или тона будет отменена. Этот параметр использует одну и только одну из констант LINETONEMODE_.

dwDuration

Длительность в миллисекундах, в течение которой поддерживается тон. Значение 0 для dwDuration использует длительность по умолчанию для указанного тона. Значения по умолчанию:

CUSTOM: бесконечный

RINGBACK: бесконечный

BUSY: бесконечный

BEEP: infinite

ВЫСТАВЛЕНИЕ СЧЕТОВ: фиксированная (один цикл)

Этот параметр не проверяется TAPI при вызове этой функции.

dwNumTones

Количество записей в массиве lpTones . Этот параметр игнорируется, если параметр dwToneMode не равен LINETONEMODE_CUSTOM.

lpTones

Указатель на массив LINEGENERATETONE , указывающий компоненты тона. Этот параметр игнорируется для ненастраиваемых тонов. Если lpTones является многочастотным, различные тона воспроизводится одновременно.

Возвращаемое значение

Возвращает ноль, если функция выполнена успешно, или номер ошибки при возникновении ошибки. Возможные возвращаемые значения:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTONEMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALTONE, LINEERR_RESOURCEUNAVAIL LINEERR_RESOURCEUNAVAIL.

TSPI_lineGenerateTone возвращает ноль (успешно) при успешном запуске создания тона; не после завершения создания тона. Функция позволяет создавать по полосам несколько предопределенных тонов, таких как мелодии звонка, тон занятости и звуковой сигнал. Он также позволяет создавать пользовательские тона, указывая частоту их компонентов, периодичность и объем, если это поддерживается поставщиком услуг. Так как эти тона создаются как повязные тона, для эффективного создания тона вызов обычно должен находиться в подключенном состоянии. После завершения создания звукового сигнала или при отмене генерации сигналов в TAPI отправляется LINE_GENERATE сообщение.

Примечание Для каждого вызова может выполняться только один запрос на создание по полосе (генерация сигналов или цифр). Это означает, что если при вызове в настоящее время выполняется создание тона, вызов TSPI_lineGenerateDigits или TSPI_lineGenerateTone отменяет создание тона. Поставщик услуг должен завершить любое генерацию звукового сигнала при вызове последующей TSPI_lineGenerateDigits или TSPI_lineGenerateTone функции.

Соответствующая функция на уровне TAPI не включает формальный параметр dwEndToEndID. На этом уровне нет сквозной маркировки. TAPI использует сквозную маркировку на уровне TSPI, чтобы отличить один TSPI_lineGenerateTone запрос от другого.