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

Статья
08/26/2023

Функция lineGatherDigits инициирует буферный сбор цифр при указанном вызове. Приложение задает буфер, в который помещает цифры и максимальное количество собираемых цифр.

Синтаксис

LONG lineGatherDigits(
  HCALL  hCall,
  DWORD  dwDigitModes,
  LPSTR  lpsDigits,
  DWORD  dwNumDigits,
  LPCSTR lpszTerminationDigits,
  DWORD  dwFirstDigitTimeout,
  DWORD  dwInterDigitTimeout
);

Параметры

hCall

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

dwDigitModes

Отслеживаемые режимы цифр. Этот параметр использует одну или несколько констант LINEDIGITMODE_.

lpsDigits

Указатель на буфер, в котором обнаруженные цифры должны храниться в виде текстовых символов. Цифры могут не отображаться в буфере по одному, так как они собираются. Только после получения LINE_GATHERDIGITS сообщения следует считать, что содержимое буфера является допустимым. Если lpsDigits имеет значение NULL, сбор цифр, который выполняется в вызове, завершается, а dwNumDigits игнорируется. В противном случае предполагается, что в lpsDigits есть место для цифр dwNumDigits .

dwNumDigits

Число цифр, собираемых перед отправкой LINE_GATHERDIGITS сообщения в приложение. Параметр dwNumDigits игнорируется, если lpsDigits имеет значение NULL. Эта функция завершается ошибкой, если параметр dwNumDigits равен нулю.

lpszTerminationDigits

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

Список допустимых символов зависит от константы, предоставленной в dwDigitModes. Список допустимых символов для каждого возможного режима см. в разделе константы LINEDIGITMODE_.

Если этот указатель имеет значение NULL или указывает на пустую строку, функция ведет себя так, как будто цифры завершения не были предоставлены.

dwFirstDigitTimeout

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

dwInterDigitTimeout

Максимальная длительность времени в миллисекундах между последовательными цифрами. Если цифра не получена в этот период времени, сбор цифр прерывается и в приложение отправляется LINE_GATHERDIGITS сообщение. Буфер содержит только цифры, собранные до этого момента, за которым следует символ NULL , указывающий на то, что время ожидания interdigit завершило сбор цифр. Возможности линейного устройства вызова указывают допустимый диапазон для этого параметра или указывают на то, что время ожидания не поддерживается.

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

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

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER LINEERR_UNINITIALIZED.

Сбор цифр завершается при сборе запрошенного количества цифр. Он также завершается, если одна из обнаруженных цифр соответствует цифре в szTerminationDigits до сбора указанного числа цифр. Обнаруженная цифра завершения также помещается в буфер и возвращается частичный буфер.

Другой способ отмены сбора цифр происходит по истечении времени ожидания. Срок действия dwFirstDigitTimeout истекает, если первая цифра не получена за этот период времени. Срок действия dwInterDigitTimout истекает, если вторая, третья (и т. д.) цифра не получена в течение этого периода времени от ранее обнаруженной цифры, и возвращается частичный буфер.

Четвертым методом завершения сбора цифр является повторный вызов этой функции во время сбора. Старый сеанс сбора завершается, все цифры, собранные до этой точки, копируются в буфер, предоставленный из предыдущего вызова этой функции, и буфер доставляется при отправке LINE_GATHERDIGITS сообщения в приложение. Механизм завершения сбора цифр без инициации другого сбора цифр заключается в вызове этой функции с параметром lpsDigits , равным NULL.

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

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

Сообщение LINE_GATHERDIGITS отправляется только приложению, которое инициировало запрос. Он также отправляется при возврате частичных буферов из-за времени ожидания или совпадения цифр завершения или при отмене запроса другим запросом lineGatherDigits в вызове. Во всех приложениях, которые являются владельцами вызова, в любой момент времени может быть активен только один запрос на сбор цифр. Учитывая асинхронное поведение операции, приложение, которое отправляет несколько запросов lineGatherDigits в быстрой последовательности, может сделать это и получить несколько LINE_GATHERDIGITS сообщений позже. Хотя это было бы необычным поведением приложения, приложение может подсчитать количество этих сообщений, чтобы обеспечить сопоставление сообщений отмены с предыдущими запросами. В любом случае следует считать допустимым только последний запрос.

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

Приложение может использовать lineMonitorDigits для включения или отключения обнаружения небуферизованных цифр. При каждом обнаружении цифры таким образом в приложение отправляется LINE_MONITORDIGITS сообщение. Для одного и того же вызова можно одновременно включить обнаружение буферизованных и небуферизованных цифр.

Сбор цифр на конференции применяется только к hConfCall, а не к отдельным участвующим звонкам.

Если функция lineGatherDigits используется для отмены предыдущего запроса на сбор цифр, функция копирует все цифры, собранные до этой точки, в буфер, указанный в исходном вызове функции. Затем функция отправляет LINE_GATHERDIGITS сообщение в приложение независимо от того, указывает ли параметр lpszDigits во втором вызове null или другой адрес.