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

Статья
08/26/2023

Функция phoneInitialize устарела. Он по-прежнему экспортируется Tapi.dll и Tapi32.dll для обратной совместимости с приложениями, использующими TAPI версий 1.3 и 1.4.

Приложения, использующие TAPI версии 2.0 или более поздней, должны использовать phoneInitializeEx .

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

Синтаксис

LONG phoneInitialize(
  LPHPHONEAPP   lphPhoneApp,
  HINSTANCE     hInstance,
  PHONECALLBACK lpfnCallback,
  LPCSTR        lpszAppName,
  LPDWORD       lpdwNumDevs
);

Параметры

lphPhoneApp

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

hInstance

Дескриптор экземпляра клиентского приложения или библиотеки DLL.

lpfnCallback

Адрес функции обратного вызова, вызываемой для определения состояния и событий на телефонном устройстве.

lpszAppName

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

lpdwNumDevs

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

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

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

PHONEERR_INVALAPPNAME, PHONEERR_INIFILECORRUPT, PHONEERR_INVALPOINTER, PHONEERR_NOMEM, PHONEERR_OPERATIONFAILED, PHONEERR_REINIT, PHONEERR_RESOURCEUNAVAIL, PHONEERR_NODEVICE, PHONEERR_NODRIVER, PHONEERR_INVALPARAM

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

Приложения не должны вызывать phoneInitialize без последующего открытия телефона (по крайней мере для мониторинга). Если приложение не отслеживает и не использует устройства, оно должно вызвать phoneShutdown , чтобы ресурсы памяти, выделенные TAPI, могли быть освобождены, если они не нужны, а сам TAPI можно выгрузить из памяти, не требуя.

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

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