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

Статья
11/20/2024

Функция 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-terminated, содержащую только отображаемые символы. Если этот параметр не null, он содержит имя, предоставленное приложением. Это имя предоставляется в структуре PHONESTATUS, чтобы указать, что приложение имеет право на устройство телефона. Если lpszFriendlyAppNameNULL, вместо этого используется имя файла модуля приложения (как возвращается функция 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.

Замечания

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

Механизм скрытого окна выбран путем указания PHONEINITIALIZEEXOPTION_USEHIDDENWINDOW в элементе dwOptions в структуре PHONEINITIALIZEEXPARA MS. В этом механизме (который является единственным механизмом, доступным для TAPI версии 1.x приложения), 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. Приложению не требуется ждать созданного дескриптора событий; Приложение может вместо этого вызвать phoneGetMessage и заблокировать ожидание очереди сообщения.
Механизм порта завершения выбирается путем указания PHONEINITIALIZEEXOPTION_USECOMPLETION PORT в элементе dwOptions dwOptions в структуре PHONEINITIALIZEEXPARAMS. В этом механизме каждый раз, когда событие телефонии должно отправляться в приложение, TAPI отправляет его приложению с помощью PostQueuedCompletionStatus на порт завершения, который приложение, указанное в элементе hCompletionPort в PHONEINITIALIZEEXPARAMS, помеченный ключом завершения, указанным приложением в элементе dwCompletionKeyPHONEINITIALIZEEXPARAMS. Приложение должно ранее создать порт завершения с помощью 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 или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.