Strutture di dati con dimensioni variabili

Quando vengono usate strutture di dati di dimensioni variabili 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 di dati e viene impostata dall'applicazione nel membro dwTotalSize membro della struttura dei dati. I membri dwUsedSize e dwNeededSize vengono compilati da TAPI. Se dwTotalSize è minore delle dimensioni della parte fissa, viene restituito LINEERR/PHONEERR_STRUCTURETOOSMALL. Se una funzione restituisce esito positivo, tutti i campi nella parte fissa sono stati compilati. I membri dwUsedSize e dwNeededSize 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 dwNeedSize è maggiore di dwUsedSize, è possibile che alcune parti variabili siano state compilate, ma che i campi di dimensioni variabile siano stati compilati in modo non definito. Nessuna parte variabile viene mai troncata e le parti variabili che verrebbero troncate a causa di spazio insufficiente sono indicate con 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 dwNeededSize byte per la struttura e chiamando di nuovo la funzione "Get" fino a quando la funzione non restituisce esito positivo e dwNeededSize è uguale a dwUsedSize. Questo problema dovrebbe verificarsi al secondo tentativo, ad eccezione delle condizioni di gara che causano modifiche alle dimensioni delle parti variabili tra le chiamate, che devono essere un evento raro.

Nota

Tutte le stringhe di testo, indipendentemente dalla codifica, in strutture di dimensioni variabili devono essere NULL-terminate in base alle normali convenzioni di gestione delle stringhe C.