Negoziazione della versione TAPI
Nel tempo, possono esistere versioni diverse per TAPI, applicazioni e provider di servizi per una linea o un telefono. Le nuove versioni possono definire nuove funzionalità, nuovi campi per le strutture di dati e così via. I numeri di versione indicano quindi come interpretare varie strutture di dati.
Per consentire un'interoperabilità ottimale di diverse versioni di applicazioni, versioni di TAPI e versioni dei provider di servizi da parte di fornitori diversi, TAPI offre un semplice meccanismo di negoziazione delle versioni in due passaggi per le applicazioni. Due versioni diverse devono essere concordate dall'applicazione, TAPI e dal provider di servizi per ogni dispositivo line. Il primo è il numero di versione per la telefonia di base e supplementare e viene definito versione DELL'API. L'altro è per le estensioni specifiche del provider, se presenti, e viene definito versione dell'estensione. Il formato delle strutture di dati e dei tipi di dati usati dalle funzionalità di base e supplementari di TAPI è definito dalla versione dell'API, mentre la versione dell'estensione determina il formato delle strutture di dati definite dalle estensioni specifiche del fornitore.
La negoziazione della versione procede in due fasi. Nella prima fase viene negoziato il numero di versione dell'API e viene ottenuto l'identificatore di estensione associato a tutte le estensioni specifiche del fornitore supportate nel dispositivo. Nella seconda fase viene negoziata la versione dell'estensione. Se l'applicazione non usa estensioni API, ignora la seconda fase e le estensioni non vengono attivate dal provider di servizi. Se l'applicazione vuole usare le estensioni, ma le estensioni del provider di servizi (l'identificatore di estensione) non vengono riconosciute dall'applicazione, l'applicazione deve ignorare anche la negoziazione per la versione dell'estensione. Ogni fornitore ha un proprio set di versioni legali (riconosciute) per ogni set di specifiche di estensione che distribuisce.
La funzione lineNegotiateAPIVersion viene usata per negoziare il numero di versione dell'API da usare. Recupera anche l'identificatore di estensione supportato dal dispositivo della riga, restituendo zeri se non sono supportate estensioni. Con questa chiamata di funzione, l'applicazione fornisce l'intervallo di versioni dell'API con cui è compatibile. TAPI a sua volta negozia con il provider di servizi della riga per determinare l'intervallo di versioni dell'API supportato. TAPI seleziona quindi un numero di versione (in genere, anche se non necessariamente, il numero di versione più alto) nell'intervallo di versione sovrapposto fornito dall'applicazione, dalla DLL e dal provider di servizi. Questo numero viene restituito all'applicazione, insieme all'identificatore di estensione che definisce le estensioni disponibili dal provider di servizi della riga.
Se l'applicazione vuole usare le estensioni definite dall'identificatore di estensione restituito, deve prima chiamare lineNegotiateExtVersion per negoziare la versione dell'estensione. In una fase di negoziazione simile, l'applicazione specifica la versione dell'API già concordata e l'intervallo di versioni dell'estensione supportato. TAPI passa queste informazioni al provider di servizi per la riga. Il provider di servizi controlla la versione dell'API e l'intervallo di versioni dell'estensione autonomamente e seleziona il numero di versione dell'estensione appropriato, se presente.
Quando l'applicazione chiama in seguito lineGetDevCaps, restituisce un set di funzionalità del dispositivo per la riga che corrisponde ai risultati della negoziazione della versione. Queste includono le funzionalità del dispositivo della riga coerenti con la versione dell'API e le funzionalità specifiche del dispositivo della riga coerenti con la versione dell'estensione. L'applicazione deve specificare entrambi i numeri di versione quando apre una riga. A questo punto, l'applicazione, la DLL e il provider di servizi si impegna a usare le versioni concordate. Se le estensioni specifiche del dispositivo non devono essere usate, la versione dell'estensione deve essere specificata come zero.
In un ambiente in cui più applicazioni aprono lo stesso dispositivo line, la prima applicazione per aprire il dispositivo line seleziona le versioni per tutte le applicazioni future che vogliono usare la riga (i provider di servizi non supportano più versioni contemporaneamente). Analogamente, un'applicazione che apre più dispositivi line può risultare più semplice usare tutti i dispositivi line con lo stesso numero di versione dell'API.
Ogni funzione che accetta un parametro dwAPIVersion o simile deve impostare questo parametro sulla versione più alta dell'API supportata dall'applicazione o sulla versione dell'API negoziata usando la funzione lineNegotiateAPIVersion o phoneNegotiateAPIVersion in un determinato dispositivo. Usare la tabella seguente come guida:
| Funzione | Significato |
|---|---|
| lineGetAddressCaps | Usare la versione restituita da lineNegotiateAPIVersion. |
| lineGetCountry | Usare la versione più recente supportata dall'applicazione. |
| lineGetDevCaps | Usare la versione restituita da lineNegotiateAPIVersion. |
| lineGetProviderList | Usare la versione più recente supportata dall'applicazione. |
| lineGetTranslateCaps | Usare la versione più recente supportata dall'applicazione. |
| lineNegotiateAPIVersion | Usare la versione più recente supportata dall'applicazione. |
| lineNegotiateExtVersion | Usare la versione restituita da lineNegotiateAPIVersion. |
| lineOpen | Usare la versione restituita da lineNegotiateAPIVersion. |
| lineTranslateAddress | Usare la versione più recente supportata dall'applicazione. |
| lineTranslateDialog | Usare la versione più recente supportata dall'applicazione. |
| phoneGetDevCaps | Usare la versione restituita da phoneNegotiateAPIVersion. |
| phoneNegotiateAPIVersion | Usare la versione più recente supportata dall'applicazione. |
| phoneNegotiateExtVersion | Usare la versione restituita da phoneNegotiateAPIVersion. |
| phoneOpen | Usare la versione restituita da phoneNegotiateAPIVersion. |
Importante
Quando si negozia una versione dell'API, impostare sempre i numeri di versione alti e bassi sull'intervallo di versioni che l'applicazione può supportare. Ad esempio, non usare mai 0x00000000 per la versione bassa o 0xFFFFFFFF per l'alto perché questi valori richiedono che l'applicazione supporti tutte le versioni di TAPI, sia passate che future.