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

Статья
08/26/2023

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

Синтаксис

LONG phoneInitializeExA(
  LPHPHONEAPP               lphPhoneApp,
  HINSTANCE                 hInstance,
  PHONECALLBACK             lpfnCallback,
  LPCSTR                    lpszFriendlyAppName,
  LPDWORD                   lpdwNumDevs,
  LPDWORD                   lpdwAPIVersion,
  LPPHONEINITIALIZEEXPARAMS lpPhoneInitializeExParams
);

Параметры

lphPhoneApp

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

hInstance

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

lpfnCallback

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

lpszFriendlyAppName

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

lpdwNumDevs

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

lpdwAPIVersion

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

lpPhoneInitializeExParams

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

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

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

PHONEERR_INVALAPPNAME, PHONEERR_OPERATIONFAILED, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_REINIT, PHONEERR_NOMEM, PHONEERR_INVALPARAM.

Механизм скрытого окна выбирается путем указания PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW в элементе dwOptions в структуре PHONEINITIALIZEEXPARAMS . В этом механизме (который является единственным механизмом, доступным для TAPI версии 1.x applications), TAPI создает окно в контексте приложения во время функции phoneInitializeEx и подклассы окна, чтобы все сообщения, опубликованные в него, обрабатывались WNDPROC в самом TAPI. Если TAPI содержит сообщение для доставки в приложение, TAPI публикует сообщение в скрытом окне. При получении сообщения (что может произойти только при вызове приложением функции Windows GetMessage ) Windows переключает контекст процесса на контекст приложения и вызывает WNDPROC в TAPI. Затем TAPI доставляет сообщение приложению, вызывая phoneCallbackFunc, указатель на который приложение указало в качестве параметра в вызове phoneInitializeEx (или phoneInitialize для приложений TAPI версии 1.3 и 1.4). Этот механизм требует, чтобы приложение должно иметь очередь сообщений (что нежелательно для процессов обслуживания) и регулярно обслуживать эту очередь, чтобы избежать задержки обработки событий телефонии. Скрытое окно уничтожается с помощью TAPI во время функции phoneShutdown .
Механизм обработки событий выбирается путем указания PHONEINITIALIZEEXOPTION_USEEVENT в элементе dwOptions в структуре PHONEINITIALIZEEXPARAMS . В этом механизме TAPI создает объект события от имени приложения и возвращает дескриптор объекта в элементе hEvent в PHONEINITIALIZEEXPARAMS. Приложение не должно управлять этим событием каким-либо образом (например, не должно вызывать SetEvent, ResetEvent, CloseHandle и т. д.) или неопределенные результаты поведения; приложение может ожидать этого события только с помощью таких функций, как WaitForSingleObject или MsgWaitForMultipleObjects. TAPI сигнализирует об этом событии всякий раз, когда для приложения ожидается уведомление о событии телефонии; приложение должно вызвать phoneGetMessage для получения содержимого сообщения. Событие сбрасывается с помощью TAPI, если события не ожидаются. Дескриптор события закрывается, а объект события уничтожается TAPI во время функции phoneShutdown . Приложению не требуется ждать созданного дескриптора события; вместо этого приложение может позвонить по телефонуGetMessage и заблокировать ожидание сообщения в очереди.
Механизм порта завершения выбирается путем указания PHONEINITIALIZEEXOPTION_USECOMPLETION PORT в элементе dwOptions в структуре PHONEINITIALIZEEXPARAMS . В этом механизме всякий раз, когда в приложение необходимо отправить событие телефонии, TAPI отправляет его приложению с помощью PostQueuedCompletionStatus на порт завершения, указанный приложением в элементе hCompletionPort в PHONEINITIALIZEEXPARAMS, помеченный ключом завершения, указанным приложением в элементе dwCompletionKey в phoneINITIALIZEEXPARAMS. Приложение должно предварительно создать порт завершения с помощью CreateIoCompletionPort. Приложения извлекают события с помощью GetQueuedCompletionStatus. При возвращении из GetQueuedCompletionStatus приложение получает указанный dwCompletionKey , записанный в DWORD , на который указывает параметр lpCompletionKey , и указатель на структуру PHONEMESSAGE , возвращенный в расположение, на которое указывает lpOverlapped. После обработки события приложение должно вызвать LocalFree , чтобы освободить память, используемую для хранения структуры PHONEMESSAGE . Так как приложение создало порт завершения (тем самым позволяя использовать его совместно для других целей), приложение должно закрыть его; приложение не должно закрывать порт завершения до вызова phoneShutdown.

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

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

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

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

Примечание

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