Согласование версий TAPI
Со временем разные версии могут существовать для поставщиков услуг TAPI, приложений и служб для линии или телефона. Новые версии могут определять новые функции, новые поля для структур данных и т. д. Поэтому номера версий указывают, как интерпретировать различные структуры данных.
Чтобы обеспечить оптимальную совместимость различных версий приложений, версий TAPI и версий поставщиков услуг различными поставщиками услуг, TAPI предоставляет простой двухфакторный механизм согласования версий для приложений. Две разные версии должны быть согласованы приложением, TAPI и поставщиком услуг для каждого устройства линии. Первым является номер версии для базовой и дополнительной телефонии и называется версией API. Другой — для расширений, относящихся к поставщику, если таковые есть, и называется версией расширения. Формат структур данных и типов данных, используемых базовыми и дополнительными функциями TAPI, определяется версией API, а версия расширения определяет формат структур данных, определенных расширениями для конкретного поставщика.
Согласование версий продолжается на двух этапах. На первом этапе номер версии API согласовывается, а идентификатор расширения, связанный с любыми расширениями, поддерживаемыми на устройстве, зависит от поставщика. На втором этапе выполняется согласование версии расширения. Если приложение не использует расширения API, он пропускает второй этап и расширения не активируются поставщиком услуг. Если приложение хочет использовать расширения, но расширения поставщика услуг (идентификатор расширения) не распознаются приложением, приложение также должно пропустить согласование версии расширения. У каждого поставщика есть собственный набор юридических (распознанных) версий для каждого набора спецификаций расширений, которые он распространяет.
Функция lineNegotiateAPIVersion используется для согласования номера версии API для использования. Он также получает идентификатор расширения, поддерживаемый устройством строки, возвращая нули, если расширения не поддерживаются. При вызове этой функции приложение предоставляет диапазон версий API, с которым он совместим. TAPI, в свою очередь, согласовывает с поставщиком услуг линии, чтобы определить, какой диапазон версий API он поддерживает. ЗАТЕМ TAPI выбирает номер версии (как правило, хотя и не обязательно, самый высокий номер версии) в перекрывающихся диапазонах версий, предоставленных приложением, библиотекой DLL и поставщиком услуг. Это число возвращается приложению вместе с идентификатором расширения, определяющим расширения, доступные поставщиком услуг этой строки.
Если приложение хочет использовать расширения, определенные возвращаемым идентификатором расширения, сначала необходимо вызвать lineNegotiateExtVersion для согласования версии расширения. На аналогичном этапе согласования приложение указывает уже согласованную версию API и поддерживаемый диапазон версий расширения. TAPI передает эти сведения поставщику услуг для строки. Поставщик услуг проверяет версию API и диапазон версий расширения по своему усмотрению и выбирает соответствующий номер версии расширения, если он существует.
Когда приложение позже вызывает lineGetDevCaps, он возвращает набор возможностей устройств для строки, соответствующей результатам согласования версий. К ним относятся возможности устройства линии, согласованные с версией API, и возможности конкретной строки, согласованные с версией расширения. Приложение должно указать оба этих номера версий при открытии строки. На этом этапе приложение, библиотека DLL и поставщик услуг привержены использованию согласованных версий. Если расширения, относящиеся к устройству, не используются, версия расширения должна быть указана как нулевая.
В среде, в которой несколько приложений открывают одно и то же устройство, первое приложение для открытия устройства линии выбирает версии для всех будущих приложений, которые хотят использовать линию (поставщики услуг не поддерживают несколько версий одновременно). Аналогичным образом, приложение, которое открывает несколько устройств линии, может упростить работу всех устройств линии под одинаковым номером версии API.
Каждая функция, принимаюющая dwAPIVersion или аналогичный параметр, должна задать этот параметр либо самой высокой версией API, поддерживаемой приложением, либо версией API, согласованной с помощью lineNegotiateAPIVersion или phoneNegotiateAPIVersion функции на определенном устройстве. Используйте следующую таблицу в качестве руководства:
| Функция | Значение |
|---|---|
| lineGetAddressCaps | Используйте версию, возвращаемую lineNegotiateAPIVersion. |
| lineGetCountry | Используйте самую высокую версию, поддерживаемую приложением. |
| lineGetDevCaps | Используйте версию, возвращаемую lineNegotiateAPIVersion. |
| lineGetProviderList | Используйте самую высокую версию, поддерживаемую приложением. |
| lineGetTranslateCaps | Используйте самую высокую версию, поддерживаемую приложением. |
| lineNegotiateAPIVersion | Используйте самую высокую версию, поддерживаемую приложением. |
| lineNegotiateExtVersion | Используйте версию, возвращаемую lineNegotiateAPIVersion. |
| lineOpen | Используйте версию, возвращаемую lineNegotiateAPIVersion. |
| lineTranslateAddress | Используйте самую высокую версию, поддерживаемую приложением. |
| lineTranslateDialog | Используйте самую высокую версию, поддерживаемую приложением. |
| phoneGetDevCaps | Используйте версию, возвращаемую phoneNegotiateAPIVersion. |
| phoneNegotiateAPIVersion | Используйте самую высокую версию, поддерживаемую приложением. |
| phoneNegotiateExtVersion | Используйте версию, возвращаемую phoneNegotiateAPIVersion. |
| phoneOpen | Используйте версию, возвращаемую phoneNegotiateAPIVersion. |
Важный
При согласовании версии API всегда задайте для диапазона версий, поддерживаемых приложением, высокий и низкий номера версий. Например, никогда не используйте 0x00000000 для низкой версии или 0xFFFFFFFF для высокой, так как эти значения требуют, чтобы ваше приложение поддерживало все версии TAPI, как прошлые, так и будущие.