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

Статья
08/26/2023

Функция TSPI_lineMonitorTones включает и отключает обнаружение сигналов по полосе при вызове. При каждом обнаружении указанного сигнала в клиентское приложение отправляется сообщение через TAPI.

Синтаксис

LONG TSPIAPI TSPI_lineMonitorTones(
  HDRVCALL                hdCall,
  DWORD                   dwToneListID,
  LPLINEMONITORTONE const lpToneList,
  DWORD                   dwNumEntries
);

Параметры

hdCall

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

dwToneListID

Уникальный идентификатор для этого списка сигналов. Несколько списков тонов могут быть неоплачены одновременно. Поставщик услуг должен заменить любой старый список, имеющий тот же dwToneListID , новым списком тонов. Если lpToneList имеет значение NULL, список тонов с dwToneListID просто удаляется. В любом случае другие тональности с разными значениями dwToneListIDсохраняются без изменений.

lpToneList

Список отслеживаемых тонов типа LINEMONITORTONE. Каждый тон в этом списке имеет определяемое приложением поле тега, которое используется для идентификации отдельных тонов в списке с целью создания отчетов об обнаружении тона. Выполняющееся отслеживание тона отменяется или изменяется путем вызова этой операции со значением NULL для lpToneList или с другим списком тонов. Поставщик услуг должен скопировать список тонов в собственную память для последующего использования, а не просто сохранять указатель в памяти приложения.

dwNumEntries

Количество записей в lpToneList. Параметр dwNumEntries игнорируется, если lpToneList имеет значение NULL. TAPI не проверяет этот параметр при вызове этой функции.

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

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

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

Эта функция возвращает ноль (успешно) при правильном запуске мониторинга тона, а не при завершении мониторинга тона. Как и при мониторинге мультимедиа, мониторинг тона остается в силе для заданного списка тонов, пока этот список не будет явно отключен путем вызова TSPI_lineMonitorTones с тем же dwToneListID и другим списком сигналов (или списком тонов NULL ) или пока вызов не перейдет в режим простоя.

Хотя эту функцию можно вызвать в любом состоянии вызова, кроме простоя, сигналы обычно могут обнаруживаться только в том случае, когда вызов находится в подключенном состоянии. Для обнаружения тона обычно требуются вычислительные ресурсы. В зависимости от поставщика услуг и других действий, конкурирующих за такие ресурсы, количество тонов, которые могут быть обнаружены, может меняться с течением времени. Кроме того, эквивалентное количество ресурсов может быть использовано для мониторинга одного тройного тона частоты по сравнению с тремя одночастотными тонами. Если ресурсы перефиксированы, поставщик служб возвращает LINEERR_RESOURCEUNAVAIL.

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

Обратите вниманиеTSPI_lineMonitorTones также используется для обнаружения тишины. Тишина указывается как тон со всеми нулевыми частотами.

Соответствующая функция на уровне TAPI не включает параметр dwToneListID . Включение этого параметра в интерфейсЕ TSPI позволяет TAPI пересылать объединение всех списков мониторинга тона из всех приложений поставщику услуг, сохраняя при этом возможность фильтрации и пересылки событий обнаружения тона в соответствии с приложением. Это дает разработчикам поставщиков услуг максимальную гибкость при определении степени, в которой они могут различать очень близкие тона, поскольку TAPI не делает предположений о том, какие описания тона считаются идентичными.