Strutture dati di dimensioni variabile

Quando le strutture dati di dimensioni variabili vengono usate per trasmettere informazioni tra TAPI e l'applicazione, l'applicazione è responsabile dell'allocazione della memoria necessaria. La quantità di memoria allocata deve essere almeno grande per la parte fissa della struttura dei dati e viene impostata dall'applicazione nel membro dwTotalSize della struttura dei dati. I membri dwUsedSize e dwNeedSize vengono compilati da TAPI. Se dwTotalSize è minore delle dimensioni della parte fissa, viene restituito lineeRR/PHONEERR_STRUCTURETOOSMALL. Se una funzione restituisce l'esito positivo, tutti i campi nella parte fissa sono stati compilati. I membri dwUsedSize e dwNeedSize possono essere confrontati per determinare se tutte le parti variabili sono state riempite e la quantità di spazio necessaria per riempirle tutte.

Se dwNeededSize è uguale a dwUsedSize, tutte le parti fisse e variabili sono state compilate. Se dwNeedEdSize è maggiore di dwUsedSize, alcune parti variabili possono essere state compilate, ma esattamente quali campi di dimensioni variabile sono stati compilati non è definito. Nessuna parte variabile viene mai troncata e le parti variabili che sarebbero state troncate a causa di spazio insufficiente sono indicate dalla presenza di entrambe le parti "Offset" e "Size" corrispondenti impostate su zero. Se non sono entrambi zero (e non è stato restituito alcun errore), indicano l'offset e le dimensioni dei dati variabili validi e non troncati.

Un'applicazione può sempre garantire che tutte le parti variabili vengano compilate allocando e indicando byte dwNeedSize per la struttura e chiamando nuovamente la funzione "Get" fino a quando la funzione restituisce esito positivo e dwNeedSize uguale a dwUsedSize. Ciò dovrebbe verificarsi nel secondo tentativo, ad eccezione delle condizioni di gara che causano modifiche nelle dimensioni delle parti variabili tra chiamate, che dovrebbero essere un'occorrenza rara.

Nota

Tutte le stringhe di testo, indipendentemente dalla codifica, devono essere terminate in modo variabile in base alle normali convenzioni di gestione delle stringhe C.