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

Статья
08/26/2023

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

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

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

Синтаксис

LONG lineInitialize(
  LPHLINEAPP   lphLineApp,
  HINSTANCE    hInstance,
  LINECALLBACK lpfnCallback,
  LPCSTR       lpszAppName,
  LPDWORD      lpdwNumDevs
);

Параметры

lphLineApp

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

hInstance

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

lpfnCallback

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

lpszAppName

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

lpdwNumDevs

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

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

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

LINEERR_INVALAPPNAME, LINEERR_OPERATIONFAILED, LINEERR_INIFILECORRUPT, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_REINIT, LINEERR_NODRIVER, LINEERR_NODEVICE, LINEERR_NOMEM LINEERR_NOMULTIPLEINSTANCE.

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

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

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

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

На всех платформах TAPI lineInitialize эквивалентна lineInitializeEx с параметром LINEINITIALIZEEXOPTION_USEHIDDENWINDOW.