Negociação de versão do TAPI
Ao longo do tempo, podem existir versões diferentes para TAPI, aplicativos e provedores de serviços para uma linha ou telefone. Novas versões podem definir novos recursos, novos campos para estruturas de dados e assim por diante. Os números de versão indicam, portanto, como interpretar várias estruturas de dados.
Para permitir a interoperabilidade ideal de diferentes versões de aplicativos, versões do próprio TAPI e versões de provedores de serviços por diferentes fornecedores, o TAPI fornece um mecanismo simples de negociação de versão em duas etapas para aplicativos. Duas versões diferentes devem ser acordadas pelo aplicativo, TAPI e o provedor de serviços para cada dispositivo de linha. O primeiro é o número de versão da Telefonia Básica e Suplementar e é conhecido como a versão da API. O outro é para extensões específicas do provedor, se houver, e é chamado de versão de extensão. O formato das estruturas de dados e dos tipos de dados usados pelos recursos básicos e suplementares do TAPI é definido pela versão da API, enquanto a versão da extensão determina o formato das estruturas de dados definidas pelas extensões específicas do fornecedor.
A negociação de versão prossegue em duas fases. Na primeira fase, o número de versão da API é negociado e o identificador de extensão associado a quaisquer extensões específicas do fornecedor com suporte no dispositivo é obtido. Na segunda fase, a versão da extensão é negociada. Se o aplicativo não usar extensões de API, ele ignorará a segunda fase e as extensões não serão ativadas pelo provedor de serviços. Se o aplicativo quiser usar extensões, mas as extensões do provedor de serviços (o identificador de extensão) não forem reconhecidas pelo aplicativo, o aplicativo também deverá ignorar a negociação para a versão de extensão. Cada fornecedor tem seu próprio conjunto de versões legais (reconhecidas) para cada conjunto de especificações de extensão que distribui.
A função lineNegotiateAPIVersion é usada para negociar o número de versão da API a ser usado. Ele também recupera o identificador de extensão compatível com o dispositivo de linha, retornando zeros se nenhuma extensão tiver suporte. Com essa chamada de função, o aplicativo fornece o intervalo de versão da API com o qual é compatível. O TAPI, por sua vez, negocia com o provedor de serviços da linha para determinar qual intervalo de versão de API ele dá suporte. EM seguida, o TAPI seleciona um número de versão (normalmente, embora não necessariamente, o número de versão mais alto) no intervalo de versão sobreposto que o aplicativo, a DLL e o provedor de serviços forneceram. Esse número é retornado ao aplicativo, juntamente com o identificador de extensão que define as extensões disponíveis do provedor de serviços dessa linha.
Se o aplicativo quiser usar as extensões definidas pelo identificador de extensão retornado, ele deverá primeiro chamar lineNegotiateExtVersion para negociar a versão da extensão. Em uma fase de negociação semelhante, o aplicativo especifica a versão da API já acordada e o intervalo de versão de extensão ao qual ele dá suporte. O TAPI passa essas informações para o provedor de serviços da linha. O provedor de serviços verifica a versão da API e o intervalo de versão da extensão em relação ao seu próprio e seleciona o número de versão de extensão apropriado, se houver.
Quando o aplicativo mais tarde chama lineGetDevCaps, ele retorna um conjunto de recursos de dispositivo para a linha que correspondem aos resultados da negociação de versão. Isso inclui os recursos de dispositivo da linha consistentes com a versão da API e as funcionalidades específicas do dispositivo da linha consistentes com a versão da extensão. O aplicativo deve especificar ambos os números de versão quando abrir uma linha. Nesse ponto, o aplicativo, a DLL e o provedor de serviços estão comprometidos em usar as versões acordadas. Se extensões específicas do dispositivo não forem usadas, a versão da extensão deverá ser especificada como zero.
Em um ambiente em que vários aplicativos abrem o mesmo dispositivo de linha, o primeiro aplicativo para abrir o dispositivo de linha seleciona as versões para todos os aplicativos futuros que desejam usar a linha (os provedores de serviços não dão suporte a várias versões simultaneamente).) Da mesma forma, um aplicativo que abre vários dispositivos de linha pode achar mais fácil operar todos os dispositivos de linha no mesmo número de versão da API.
Cada função que usa um dwAPIVersion ou um parâmetro semelhante deve definir esse parâmetro como a versão mais alta da API compatível com o aplicativo ou a versão da API negociada usando a função lineNegotiateAPIVersion ou phoneNegotiateAPIVersion em um dispositivo específico. Use a tabela a seguir como guia:
| Função | Significado |
|---|---|
| Linegetaddresscaps | Use a versão retornada por lineNegotiateAPIVersion. |
| lineGetCountry | Use a versão mais alta compatível com o aplicativo. |
| Linegetdevcaps | Use a versão retornada por lineNegotiateAPIVersion. |
| lineGetProviderList | Use a versão mais alta compatível com o aplicativo. |
| Linegettranslatecaps | Use a versão mais alta compatível com o aplicativo. |
| Linenegotiateapiversion | Use a versão mais alta compatível com o aplicativo. |
| lineNegotiateExtVersion | Use a versão retornada por lineNegotiateAPIVersion. |
| Lineopen | Use a versão retornada por lineNegotiateAPIVersion. |
| Linetranslateaddress | Use a versão mais alta compatível com o aplicativo. |
| Linetranslatedialog | Use a versão mais alta compatível com o aplicativo. |
| Phonegetdevcaps | Use a versão retornada por phoneNegotiateAPIVersion. |
| Phonenegotiateapiversion | Use a versão mais alta compatível com o aplicativo. |
| phoneNegotiateExtVersion | Use a versão retornada por phoneNegotiateAPIVersion. |
| phoneOpen | Use a versão retornada por phoneNegotiateAPIVersion. |
Importante
Ao negociar uma versão de API, sempre defina os números de versão alto e baixo para o intervalo de versões às quais seu aplicativo pode dar suporte. Por exemplo, nunca use 0x00000000 para a versão baixa ou 0xFFFFFFFF para alta porque esses valores exigem que seu aplicativo dê suporte a todas as versões do TAPI, passadas e futuras.