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

Статья
03/08/2023

Функция lineOpen открывает устройство линии, указанное идентификатором устройства, и возвращает дескриптор строки для соответствующего открытого линейного устройства. Этот дескриптор строки используется в последующих операциях на устройстве линии.

Синтаксис

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Параметры

hLineApp

Обработка регистрации приложения с помощью TAPI.

dwDeviceID

Идентифицирует открывающееся линейное устройство. Это может быть допустимый идентификатор устройства или значение.

Значение	Значение
LINEMAPPER	Это значение используется для открытия линейного устройства в системе, поддерживающего свойства, указанные в lpCallParams. Приложение может использовать lineGetID для определения идентификатора открытого линейного устройства.

Значение

LINEMAPPER

Это значение используется для открытия линейного устройства в системе, поддерживающего свойства, указанные в lpCallParams. Приложение может использовать lineGetID для определения идентификатора открытого линейного устройства.

lphLine

Указатель на дескриптор HLINE, который затем загружается с дескриптором, представляющим открытое устройство линии. Используйте этот дескриптор для идентификации устройства при вызове других функций на устройстве с открытой линией.

dwAPIVersion

Номер версии API, под которым приложение и API телефонии согласились работать. Это число получается с помощью lineNegotiateAPIVersion.

dwExtVersion

Дополнительный номер версии, под которым приложение и поставщик услуг соглашаются работать. Это число равно нулю, если приложение не использует расширения. Это число получается с помощью lineNegotiateExtVersion.

dwCallbackInstance

Данные экземпляра пользователя передаются приложению с каждым сообщением, связанным с этой строкой, с адресами или вызовами в этой строке. Этот параметр не интерпретируется API телефонии.

dwPrivileges

Привилегии, необходимые приложению при уведомлении о вызове Этот параметр содержит одну или несколько констант LINECALLPRIVILEGE_. Для приложений, использующих TAPI версии 2.0 или более поздней, значения этого параметра также можно объединить с одной или несколькими константами LINEOPENOPTION_.

Если указан параметр LINEOPENOPTION_SINGLEADDRESS, приложение интересует только новые вызовы, которые отображаются по адресу, указанному членом dwAddressID в структуре LINECALLPARAMS , на которую указывает параметр lpCallParams (который должен быть указан).

Если указано LINEOPENOPTION_SINGLEADDRESS, но lpCallParams является недопустимым или включенный dwAddressID не существует в строке, открытие завершается сбоем с LINERR_INVALADDRESSID.

Помимо задания нужного адреса для элемента dwAddressID структуры LINECALLPARAMS , приложение также должно задать параметру dwAddressMode в LINECALLPARAMS значение LINEADDRESSMODE_ADDRESSID.

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

Если указан параметр LINEOPENOPTION_PROXY (только TAPI 2.0 или более поздней версии), приложение также должно указать, какие конкретные запросы прокси-сервера подготовлены для обработки. Это делается путем передачи в параметре lpCallParams указателя на структуру LINECALLPARAMS , в которой члены dwDevSpecificSize и dwDevSpecificOffset были заданы для разделения массива DWORD. Каждый элемент этого массива должен содержать одну из констант LINEPROXYREQUEST_. Например, приложение обработчика прокси-сервера, поддерживающее все пять функций, связанных с агентом, будет передавать массив из пяти DWORD(dwDevSpecificSize будет иметь значение 20 десятичных разрядов), содержащий пять определенных LINEPROXYREQUEST_ значений.

Приложение обработчика запросов прокси-сервера может выполняться на любом компьютере с авторизацией для управления линейным устройством. Однако запросы всегда направляются через сервер, на котором выполняется поставщик услуг, который фактически управляет устройством линии. Таким образом, это наиболее эффективно, если приложение, обрабатывающее запросы прокси-сервера (например, управление агентом ACD), выполняется непосредственно на сервере вместе с поставщиком услуг.

Последующие попытки того же приложения или других приложений открыть линейное устройство и зарегистрироваться для обработки запросов прокси-сервера, которые уже зарегистрированы приложением, завершаются сбоем с LINEERR_NOTREGISTERED.

Чтобы остановить обработку запросов в строке, приложение просто вызывает lineClose.

Другие сочетания флагов возвращают ошибку LINEERR_INVALPRIVSELECT.

dwMediaModes

Тип или режимы мультимедиа, представляющие интерес для приложения. Этот параметр используется для регистрации приложения в качестве потенциального целевого объекта для входящего вызова и передачи вызовов для указанного типа мультимедиа. Этот параметр имеет смысл, только если задан битовый LINECALLPRIVILEGE_OWNER в dwPrivileges (в противном случае игнорируется). Этот параметр использует одну или несколько констант LINEMEDIAMODE_.

lpCallParams

Указатель на структуру типа LINECALLPARAMS. Этот указатель используется, только если используется LINEMAPPER или LINEOPENOPTION_PROXY; в противном случае lpCallParams игнорируется. В нем описывается параметр вызова, который должен быть предоставлен линейным устройством.

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

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

LINEERR_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE LINEERR_OPERATIONUNAVAIL.

Если возвращается LINEERR_ALLOCATED, строка не может быть открыта из-за "постоянного" условия, например из-за того, что последовательный порт открывается исключительно другим процессом. Если возвращается LINEERR_RESOURCEUNAVAIL, строка не может быть открыта из-за динамического переувыполнения ресурсов, таких как циклы процессора DSP или память. Это превышение активности может быть временным, вызванным мониторингом типов мультимедиа или тонов, а изменения в этих действиях другими приложениями могут позволить повторно открыть строку в течение короткого периода времени. Если возвращается LINEERR_REINIT и запрашивается повторное инициализация TAPI (например, в результате добавления или удаления поставщика услуг телефонии), запросы lineOpen отклоняются с этой ошибкой, пока последнее приложение не завершит использование API (с помощью lineShutdown); В это время новая конфигурация вступает в силу, и приложениям снова разрешено вызывать lineInitializeEx.

Открытие строки всегда дает приложению право совершать вызовы по любому адресу, доступному в строке. Возможность приложения работать с входящими вызовами или быть целью передачи вызовов в строке определяется параметром dwMediaModes . Функция lineOpen регистрирует приложение как заинтересованное в мониторинге вызовов или получении прав владения вызовами, которые относятся к указанным типам мультимедиа. Если приложение просто хочет отслеживать вызовы, оно может указать LINECALLPRIVILEGE_MONITOR. Если приложение просто хочет совершать исходящие вызовы, оно может указать LINECALLPRIVILEGE_NONE. Если приложение готово управлять неклассифицированными вызовами (вызовами неизвестного типа мультимедиа), оно может указать LINECALLPRIVILEGE_OWNER и LINEMEDIAMODE_UNKNOWN. В противном случае приложение должно указать тип мультимедиа, который оно должно обрабатывать. Приложение может вызвать функцию lineSetCallPrivilege , чтобы изменить привилегии вызова, заданные LINECALLPRIVILEGES_Constants.

Типы мультимедиа, указанные с помощью lineOpen , добавляются к значению по умолчанию для мониторинга типа мультимедиа поставщика для определения исходного типа входящего вызова. Функция lineMonitorMedia изменяет маску, которая управляет LINE_MONITORMEDIA сообщений. Если линейное устройство открыто с привилегией владельца и тип носителя расширения не зарегистрирован, возвращается LINEERR_INVALMEDIAMODE ошибки.

Приложение, которое успешно открыло линейное устройство, всегда может инициировать вызовы с помощью lineMakeCall, lineUnpark, linePickup и lineSetupConference (с nullhCall), а также использовать lineForward (при условии, что это разрешено возможностями устройства, состоянием строки и т. д.).

Одно приложение может одновременно указать несколько флагов для обработки нескольких типов мультимедиа. Конфликты могут возникнуть, если несколько приложений открывают одно и то же устройство строки для одного и того же типа мультимедиа. Эти конфликты разрешаются схемой приоритета, в которой пользователь назначает приложениям относительные приоритеты. Пользователи могут задавать приоритеты приложений, вызывая функцию lineSetAppPriority . Только приложение с наивысшим приоритетом для заданного типа мультимедиа когда-либо получит право владения (незапрашиваемого) вызова этого типа мультимедиа. Владение может быть получено при первом поступлении входящего звонка или при отправке звонка. Функция lineHandoff вызывается для передачи права владения вызовом другому приложению. Если пользователь не назначает приоритеты приложению и несколько приложений открывают одно и то же устройство линии, по умолчанию приложение, которое первым вызывало lineOpen , будет иметь наивысший приоритет.

Любое приложение (включая любое приложение с более низким приоритетом) всегда может получить права владения с помощью lineGetNewCalls или lineGetConfRelatedCalls. Если приложение открывает строку для мониторинга в то время, когда вызовы существуют в строке, LINE_CALLSTATE сообщения для этих существующих вызовов не создаются автоматически в новом приложении мониторинга. Приложение может запрашивать количество текущих вызовов в строке, чтобы определить, сколько вызовов существует, и при необходимости может вызывать lineGetNewCalls для получения дескрипторов этих вызовов.

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

Одно и то же приложение или различные экземпляры одного и того же приложения могут открывать одну и ту же строку несколько раз с теми же или разными параметрами.

Когда приложение открывает устройство, оно должно указать согласованную версию API, а если оно хочет использовать расширения строки, оно должно указать версию расширения для конкретного устройства строки. Эти номера версий должны быть получены с помощью lineNegotiateAPIVersion и lineNegotiateExtVersion. Нумерирование версий позволяет сочетать и сопоставлять разные версии приложений с разными версиями API и версиями поставщика служб.

LINEMAPPER позволяет приложению выбрать строку косвенно с помощью нужных служб. При открытии линейного устройства с помощью LINEMAPPER верно следующее. Все элементы от начала структуры данных LINECALLPARAMS до dwAddressMode являются актуальными. Если параметр dwAddressMode LINEADDRESSMODE_ADDRESSID это означает, что любой адрес в строке допустим. В противном случае, если параметр dwAddressMode LINEADDRESSMODE_DIALABLEADDR, указывающий, что выполняется поиск определенного исходного адреса (номера телефона), или если это расширение для конкретного поставщика, то dwOrigAddressSize/Offset и часть переменной, на которую они ссылаются, также имеют значение. Если dwAddressMode является расширением для конкретного поставщика, дополнительные сведения могут содержаться в члене dwDeviceSpecific с изменяющимися размерами.