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

Статья
03/02/2024

Функция lineInitializeEx инициализирует использование TAPI приложением для последующего использования абстракции строк. Он регистрирует указанный в приложении механизм уведомления и возвращает количество устройств, доступных для приложения. Линейное устройство — это любое устройство, которое предоставляет реализацию функций с префиксом строки в API телефонии.

Синтаксис

LONG lineInitializeExA(
  LPHLINEAPP               lphLineApp,
  HINSTANCE                hInstance,
  LINECALLBACK             lpfnCallback,
  LPCSTR                   lpszFriendlyAppName,
  LPDWORD                  lpdwNumDevs,
  LPDWORD                  lpdwAPIVersion,
  LPLINEINITIALIZEEXPARAMS lpLineInitializeExParams
);

Параметры

lphLineApp

Указатель на расположение, заполненное дескриптором использования приложения для TAPI.

hInstance

Дескриптор экземпляра клиентского приложения или библиотеки DLL. Приложение или библиотека DLL могут передать значение NULL для этого параметра. В этом случае TAPI использует дескриптор модуля корневого исполняемого файла процесса (для определения целевых объектов передачи вызовов и приоритетов режима мультимедиа).

lpfnCallback

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

lpszFriendlyAppName

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

lpdwNumDevs

Указатель на расположение размера DWORD. После успешного выполнения этого запроса это расположение заполняется количеством устройств, доступных для приложения.

lpdwAPIVersion

Указатель на расположение размера DWORD. Приложение должно инициализировать этот DWORD перед вызовом этой функции в максимальной версии API, для поддержки ( например, то же значение, которое оно будет передавать в параметр dwAPIHighVersionlineNegotiateAPIVersion). Не следует использовать искусственно высокие значения; значение должно быть точно задано. TAPI преобразует все новые сообщения или структуры в значения или форматы, поддерживаемые версией приложения. После успешного выполнения этого запроса это расположение заполняется самой высокой версией API, поддерживаемой TAPI, что позволяет приложению обнаруживать и адаптироваться к установке в системе с другой версией TAPI.

lpLineInitializeExParams

Указатель на структуру типа LINEINITIALIZEEXPARAMS , содержащую дополнительные параметры, используемые для установления связи между приложением и TAPI (в частности, выбранный механизм уведомления о событиях приложения и связанные параметры).

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

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

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NOMEM LINEERR_INVALPARAM.

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

Механизм скрытого окна выбирается путем указания LINEINITIALIZEEXOPTION_USEHIDDENWINDOW в элементе dwOptions в структуре LINEINITIALIZEEXPARAMS . В этом механизме (который является единственным механизмом, доступным для TAPI версии 1.x applications), TAPI создает окно в контексте приложения во время функции lineInitializeEx или lineInitialize (для приложений TAPI версии 1.3 и 1.4) и подклассы окна, чтобы все сообщения, опубликованные в него, обрабатывались WNDPROC в самом TAPI. Если TAPI содержит сообщение для доставки в приложение, TAPI отправляет сообщение в скрытое окно. При получении сообщения (что может произойти только при вызове приложением функции Windows GetMessage ) Windows переключает контекст процесса на контекст приложения и вызывает WNDPROC в TAPI. Затем TAPI доставляет сообщение приложению, вызывая lineCallbackProc, указатель на который приложение указало в качестве параметра при вызове lineInitializeEx (или lineInitialize). Для этого механизма приложение должно иметь очередь сообщений (что нежелательно для процессов обслуживания) и регулярно обслуживать эту очередь, чтобы избежать задержки обработки событий телефонии. Скрытое окно уничтожается с помощью ФУНКЦИИ TAPI во время функции lineShutdown .

Механизм обработки событий выбирается путем указания LINEINITIALIZEEXOPTION_USEEVENT в элементе dwOptions в структуре LINEINITIALIZEEXPARAMS . В этом механизме TAPI создает объект события от имени приложения и возвращает дескриптор объекту в элементе hEvent в LINEINITIALIZEEXPARAMS. Приложение не должно управлять этим событием каким-либо образом (например, не должно вызывать SetEvent, ResetEvent, CloseHandle и т. д.) или неопределенные результаты поведения; приложение может ожидать этого события только с помощью таких функций, как WaitForSingleObject или MsgWaitForMultipleObjects. TAPI сигнализирует об этом событии всякий раз, когда приложение ожидает уведомления о событии телефонии; приложение должно вызвать lineGetMessage , чтобы получить содержимое сообщения. Событие сбрасывается с помощью TAPI, если события не ожидаются. Дескриптор события закрывается, а объект события уничтожается TAPI во время функции lineShutdown . Приложению не требуется ожидать созданного дескриптора событий; вместо этого приложение может вызвать lineGetMessage и заблокировать ожидание постановки сообщения в очередь.

Механизм порта завершения выбирается путем указания LINEINITIALIZEEXOPTION_USECOMPLETION PORT в элементе dwOptions в структуре LINEINITIALIZEEXPARAMS . В этом механизме всякий раз, когда в приложение требуется отправить событие телефонии, TAPI отправляет его с помощью PostQueuedCompletionStatus на порт завершения, указанный приложением в члене hCompletionPort в LINEINITIALIZEEXPARAMS, помеченный ключом завершения, указанным приложением в элементе dwCompletionKey в lineINITIALIZEEXPARAMS. Приложение должно ранее создать порт завершения с помощью CreateIoCompletionPort. Приложение извлекает события с помощью GetQueuedCompletionStatus. При возвращении из GetQueuedCompletionStatus приложение имеет указанный dwCompletionKey , записанный в DWORD , на который указывает параметр lpCompletionKey , и указатель на структуру LINEMESSAGE , возвращенную в расположение, на которое указывает lpOverlapped. После обработки события приложение отвечает за вызов LocalFree , чтобы освободить память, используемую для хранения структуры LINEMESSAGE . Так как приложение создало порт завершения (тем самым предоставляя доступ к нему для других целей), приложение должно закрыть его; приложение не должно закрывать порт завершения до тех пор, пока не вызовет lineShutdown.

Если многопоточное приложение использует механизм обработки событий и несколько потоков ожидает дескриптора или механизм уведомления о порте завершения и несколько потоков ожидают на порту, события телефонии могут обрабатываться не последовательность. Это происходит не из-за последовательности доставки событий из TAPI, а из-за срезов времени потоков или выполнения потоков на отдельных процессорах.

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

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

Приложение может ссылаться на отдельные линейные устройства с помощью идентификаторов устройств, которые варьируются от нуля до dwNumDevs минус единица. Приложение не должно предполагать, что эти линейные устройства поддерживают какую-либо определенную функцию TAPI, не запрашивая возможности устройства с помощью lineGetDevCaps и lineGetAddressCaps.

Примечание

Заголовок tapi.h определяет lineInitializeEx в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.