Negociación de versiones de TAPI
Con el tiempo, pueden existir diferentes versiones para TAPI, aplicaciones y proveedores de servicios para una línea o teléfono. Las nuevas versiones pueden definir nuevas características, nuevos campos para estructuras de datos, etc. Por lo tanto, los números de versión indican cómo interpretar varias estructuras de datos.
Para permitir una interoperabilidad óptima de diferentes versiones de aplicaciones, versiones de TAPI y versiones de proveedores de servicios por diferentes proveedores, TAPI proporciona un mecanismo de negociación de versiones simple y de dos pasos para las aplicaciones. La aplicación, TAPI y el proveedor de servicios deben acordar dos versiones diferentes para cada dispositivo de línea. La primera es el número de versión de telefonía básica y complementaria y se conoce como la versión de la API. El otro es para extensiones específicas del proveedor, si las hay, y se conoce como la versión de la extensión. El formato de las estructuras de datos y los tipos de datos utilizados por las características básicas y complementarias de TAPI se define mediante la versión de la API, mientras que la versión de extensión determina el formato de las estructuras de datos definidas por las extensiones específicas del proveedor.
La negociación de versiones continúa en dos fases. En la primera fase, se negocia el número de versión de la API y se obtiene el identificador de extensión asociado a las extensiones específicas del proveedor admitidas en el dispositivo. En la segunda fase, se negocia la versión de la extensión. Si la aplicación no usa ninguna extensión de API, omite la segunda fase y el proveedor de servicios no activa las extensiones. Si la aplicación desea usar extensiones, pero la aplicación no reconoce las extensiones del proveedor de servicios (el identificador de extensión), la aplicación también debe omitir la negociación de la versión de extensión. Cada proveedor tiene su propio conjunto de versiones legales (reconocidas) para cada conjunto de especificaciones de extensión que distribuye.
La función lineNegotiateAPIVersion se usa para negociar el número de versión de la API que se va a usar. También recupera el identificador de extensión admitido por el dispositivo de línea, devolviendo ceros si no se admiten extensiones. Con esta llamada de función, la aplicación proporciona el intervalo de versiones de api con el que es compatible. TAPI a su vez negocia con el proveedor de servicios de la línea para determinar qué intervalo de versiones de API admite. A continuación, TAPI selecciona un número de versión (normalmente, aunque no necesariamente, el número de versión más alto) en el intervalo de versiones superpuesto que la aplicación, el archivo DLL y el proveedor de servicios han proporcionado. Este número se devuelve a la aplicación, junto con el identificador de extensión que define las extensiones disponibles desde el proveedor de servicios de esa línea.
Si la aplicación quiere usar las extensiones definidas por el identificador de extensión devuelto, primero debe llamar a lineNegotiateExtVersion para negociar la versión de la extensión. En una fase de negociación similar, la aplicación especifica la versión de API ya acordada y el intervalo de versiones de la extensión que admite. TAPI pasa esta información al proveedor de servicios de la línea. El proveedor de servicios comprueba la versión de la API y el intervalo de versiones de la extensión en su propio y selecciona el número de versión de extensión adecuado, si existe uno.
Cuando la aplicación llama posteriormente a lineGetDevCaps, devuelve un conjunto de funcionalidades de dispositivo para la línea que corresponden a los resultados de la negociación de versiones. Entre ellas se incluyen las funcionalidades del dispositivo de la línea coherentes con la versión de API y las funcionalidades específicas del dispositivo de la línea coherentes con la versión de extensión. La aplicación debe especificar ambos números de versión cuando se abre una línea. En ese momento, la aplicación, el archivo DLL y el proveedor de servicios se confirman en usar las versiones acordadas. Si no se van a usar extensiones específicas del dispositivo, la versión de la extensión debe especificarse como cero.
En un entorno donde varias aplicaciones abren el mismo dispositivo de línea, la primera aplicación para abrir el dispositivo de línea selecciona las versiones de todas las aplicaciones futuras que quieran usar la línea (los proveedores de servicios no admiten varias versiones simultáneamente). De forma similar, una aplicación que abre varios dispositivos de línea puede resultar más fácil operar todos los dispositivos de línea con el mismo número de versión de API.
Todas las funciones que toman un dwAPIVersion o un parámetro similar deben establecer este parámetro en la versión de API más alta admitida por la aplicación o la versión de API negociada mediante la función lineNegotiateAPIVersion o phoneNegotiateAPIVersion en un dispositivo determinado. Use la siguiente tabla como guía:
| Función | Significado |
|---|---|
| lineGetAddressCaps | Use la versión devuelta por lineNegotiateAPIVersion. |
| lineGetCountry | Use la versión más alta compatible con la aplicación. |
| lineGetDevCaps | Use la versión devuelta por lineNegotiateAPIVersion. |
| lineGetProviderList | Use la versión más alta compatible con la aplicación. |
| lineGetTranslateCaps | Use la versión más alta compatible con la aplicación. |
| lineNegotiateAPIVersion | Use la versión más alta compatible con la aplicación. |
| lineNegotiateExtVersion | Use la versión devuelta por lineNegotiateAPIVersion. |
| lineOpen | Use la versión devuelta por lineNegotiateAPIVersion. |
| lineTranslateAddress | Use la versión más alta compatible con la aplicación. |
| lineTranslateDialog | Use la versión más alta compatible con la aplicación. |
| phoneGetDevCaps | Use la versión devuelta por phoneNegotiateAPIVersion. |
| phoneNegotiateAPIVersion | Use la versión más alta compatible con la aplicación. |
| phoneNegotiateExtVersion | Use la versión devuelta por phoneNegotiateAPIVersion. |
| phoneOpen | Use la versión devuelta por phoneNegotiateAPIVersion. |
Importante
Al negociar una versión de API, establezca siempre los números de versión alta y baja en el intervalo de versiones que la aplicación puede admitir. Por ejemplo, nunca use 0x00000000 para la versión baja o 0xFFFFFFFF para el alto, ya que estos valores requieren que la aplicación admita todas las versiones de TAPI, tanto pasadas como futuras.