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

Статья
11/20/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 , чтобы указать, как понятно, какое приложение было создано, или первоначально принято или ответило на вызов. Эти сведения могут быть полезны для целей ведения журнала звонков. Если lpszFriendlyAppNameNULL, вместо этого используется имя файла модуля приложения (как возвращается функция 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 в структуре LINEINITIALIZEEXPARA MS. В этом механизме (который является единственным механизмом, доступным для TAPI версии 1.приложениях x), 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 hEvent в LINEINITIALIZEEXPARAMS. Приложение не должно управлять этим событием каким-либо образом (например, не следует вызывать SetEvent, ResetEvent, CloseHandleи т. д.) или неопределенные результаты поведения; Приложение может ждать только этого события с помощью таких функций, как WaitForSingleObject или MsgWaitForMultipleObjects. TAPI сигнализирует об этом событии всякий раз, когда уведомление о событии телефонии ожидается для приложения; Приложение должно вызвать lineGetMessage, чтобы получить содержимое сообщения. Событие сбрасывается с помощью TAPI, если события не ожидаются. Дескриптор события закрывается и объект события, уничтоженный TAPI во время функции lineShutdown. Приложению не требуется ждать созданного дескриптора событий; Приложение может вместо этого вызвать lineGetMessage и заблокировать ожидание очереди сообщения.

Механизм порта завершения выбирается путем указания LINEINITIALIZEEXOPTION_USECOMPLETION PORT в элементе dwOptions в структуре LINEINITIALIZEEXPARA MS. В этом механизме каждый раз, когда событие телефонии должно отправляться в приложение, 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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.