функция TSPI_providerInit (tspi.h)

Статья
08/26/2023

Функция TSPI_providerInit инициализирует поставщика услуг и предоставляет ему параметры, необходимые для последующих операций.

Синтаксис

LONG TSPIAPI TSPI_providerInit(
  DWORD            dwTSPIVersion,
  DWORD            dwPermanentProviderID,
  DWORD            dwLineDeviceIDBase,
  DWORD            dwPhoneDeviceIDBase,
  DWORD_PTR        dwNumLines,
  DWORD_PTR        dwNumPhones,
  ASYNC_COMPLETION lpfnCompletionProc,
  LPDWORD          lpdwTSPIOptions
);

Параметры

dwTSPIVersion

Версия определения TSPI, в которой должна работать эта функция. Вызывающий объект может использовать TSPI_lineNegotiateTSPIVersion со специальным INITIALIZE_NEGOTIATIONdwDeviceID для согласования версии, гарантированно приемлемой для поставщика услуг.

dwPermanentProviderID

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

dwLineDeviceIDBase

Самый низкий идентификатор устройства для устройств линии, поддерживаемых этим поставщиком услуг.

dwPhoneDeviceIDBase

Самый низкий идентификатор устройства для телефонных устройств, поддерживаемых этим поставщиком услуг.

dwNumLines

Количество линейных устройств, поддерживаемых поставщиком услуг. Возвращаемое значение — это количество устройств строки, сообщаемых в TSPI_providerEnumDevices.

dwNumPhones

Количество телефонных устройств, поддерживаемых поставщиком услуг. Возвращаемое значение — это количество телефонных устройств, зарегистрированных в TSPI_providerEnumDevices.

lpfnCompletionProc

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

lpdwTSPIOptions

Указатель на расположение памяти размера DWORD, в которое поставщик услуг может записать значение, указывающее LINETSPIOPTIONS_ значения. Этот параметр позволяет поставщику услуг возвращать биты, указывающие на необязательное поведение, требуемое для TAPI. TAPI устанавливает для параметра DWORD значение 0 перед вызовом TSPI_providerInit, поэтому, если поставщику услуг не нужны какие-либо из этих параметров, он может просто оставить параметр DWORD равным 0.

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

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

TAPI не сериализует доступ к функциям TSPI, отображающим диалоговое окно ( TUISPI_lineConfigDialog, TUISPI_lineConfigDialogEdit, TUISPI_phoneConfigDialog, TUISPI_providerConfig, TUISPI_providerInstall TUISPI_providerRemove), чтобы они не блокируют вызов других функций TSPI; поставщик услуг должен включать внутреннюю защиту для этих функций.

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

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

LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_OPERATIONFAILED, LINEERR_NOMEM, LINEERR_RESOURCEUNAVAIL, LINEERR_INIFILECORRUPT LINEERR_NOMULTIPLEINSTANCE.

Эта функция гарантированно будет вызвана перед любой из других функций с префиксом TSPI_line или TSPI_phone за исключением TSPI_lineNegotiateTSPIVersion. Она строго связана с последующим вызовом TSPI_providerShutdown Эти пары могут перекрываться, например, если при выполнении операций телефонии используется служебная программа панель управления телефонии, поставляемая с телефонией Windows в версиях 1.4 и более ранних версиях. Вызов этой функции должен быть проигнорирован (возвращая успешное выполнение), если уже имеется неоплаченная пара.

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

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