Функция lineGenerateTone (tapi.h)

Статья
03/02/2024

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

Синтаксис

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

Параметры

hCall

Дескриптор вызова, в котором должен быть создан тон. Приложение должно быть владельцем вызова. Состояние вызова hCall может быть любым.

dwToneMode

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

dwDuration

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

CUSTOM: тон сохраняется до тех пор, пока он не будет отключен, как правило, из-за взаимодействия с пользователем или времени ожидания оборудования.

RINGBACK: тон сохраняется до тех пор, пока он не будет отключен, как правило, в связи с взаимодействием с пользователем или временем ожидания оборудования.

BUSY: Тон сохраняется до тех пор, пока он не будет отключен, как правило, из-за взаимодействия с пользователем или времени ожидания оборудования.

BEEP: тон сохраняется до тех пор, пока он не будет отключен, как правило, в случае взаимодействия с пользователем или времени ожидания оборудования.

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

dwNumTones

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

lpTones

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

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

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

LINEERR_INVALCALLHANDLE, LINEERR_NOTOWNER, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPOINTER, LINEERR_OPERATIONFAILED, LINEERR_INVALTONEMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALTONE, LINEERR_UNINITIALIZED LINEERR_NOMEM.

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

Для каждого вызова во всех приложениях, которые являются владельцами вызова, может выполняться только один запрос на создание по полосе (генерация сигналов или цифр). Это означает, что если при вызове в настоящее время выполняется создание тона, вызов lineGenerateDigits отменяет создание тона.

Если возвращается значение ошибки LINEERR_INVALPOINTER, указанный параметр lpTones является недопустимым или значение, указанное параметром dwNumTones, слишком велико.