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

Статья
03/09/2024

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

Владение телефонным устройством является эксклюзивным. Иными словами, только одно приложение может одновременно открывать телефонное устройство с правами владельца. Однако телефонное устройство можно открывать несколько раз с правами монитора.

Синтаксис

LONG phoneOpen(
  HPHONEAPP hPhoneApp,
  DWORD     dwDeviceID,
  LPHPHONE  lphPhone,
  DWORD     dwAPIVersion,
  DWORD     dwExtVersion,
  DWORD_PTR dwCallbackInstance,
  DWORD     dwPrivilege
);

Параметры

hPhoneApp

Обработка регистрации приложения с помощью TAPI.

dwDeviceID

Идентификатор открываемого телефонного устройства.

lphPhone

Указатель на дескриптор HPHONE, который идентифицирует открытое телефонное устройство. Используйте этот дескриптор для идентификации устройства при вызове других функций управления телефоном.

dwAPIVersion

Номер версии API, под которым приложение и API телефонии согласились работать. Это число получается из phoneNegotiateAPIVersion.

dwExtVersion

Дополнительный номер версии, под которым приложение и поставщик услуг соглашаются работать. Это число равно нулю, если приложение не использует расширения. Этот номер получается из phoneNegotiateExtVersion.

dwCallbackInstance

Данные пользовательского экземпляра передаются приложению с каждым сообщением. Этот параметр не интерпретируется API телефонии.

dwPrivilege

Запрошенные привилегии. Этот параметр использует только одну из констант PHONEPRIVILEGE_.

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

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

PHONEERR_ALLOCATED, PHONEERR_NODRIVER, PHONEERR_BADDEVICEID, PHONEERR_NOMEM, PHONEERR_INCOMPATIBLEAPIVERSION, PHONEERR_OPERATIONFAILED, PHONEERR_INCOMPATIBLEEXTVERSION, PHONEERR_OPERATIONUNAVAIL, PHONEERR_INVALAPPHANDLE, PHONEERR_RESOURCEUNAVAIL, PHONEERR_INVALPOINTER, PHONEERR_UNINITIALIZED, PHONEERR_INVALPRIVILEGE, PHONEERR_REINIT, PHONEERR_INUSE, PHONEERR_NODEVICE, PHONEERR_INIFILECORRUPT.

При открытии телефонного устройства с правами монитора приложение отправляет сообщения при возникновении событий, которые изменяют состояние телефона. Сообщения, отправляемые приложению, включают PHONE_BUTTON и PHONE_STATE. Последний предоставляет сведения об изменении элемента состояния телефона.

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

Когда приложение открывает телефонное устройство, оно должно указать согласованную версию API, а если оно хочет использовать расширения телефона, версию расширения для конкретного устройства телефона. Этот номер версии должен быть получен с помощью функций phoneNegotiateAPIVersion и phoneNegotiateExtVersion . Нумерирование версий позволяет сочетать и сопоставлять разные версии приложений с разными версиями API и версиями поставщика услуг.