Allocazione della memoria

Le applicazioni devono allocare memoria per questi dati; TAPI e il provider di servizi forniscono i dati. Se l'operazione è asincrona, i dati non sono disponibili finché il messaggio di risposta asincrona indica l'esito positivo.

Tutte le strutture di dati usate per passare i dati tra l'applicazione e il TAPI vengono appiattite. Ovvero, le strutture dati non contengono puntatori alle sottostruttura che contengono componenti dati di dimensioni variabile. Le strutture dati usate per passare di nuovo quantità di dati variabili all'applicazione devono avere la metastruttura seguente:

  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize; 
    <fixed size fields> 
  DWORD  dw<VarSizeField1>Size;
  DWORD  dw<VarSizeField1>Offset; 
    <fixed size fields> 
  DWORD  dw<VarSizeField2>Size;
  DWORD  dw<VarSizeField2>Offset; 
    <common extensions> 
    <var sized field1> 
    <var sized field2>

Il membro dwTotalSize è la dimensione, in byte, allocata a questa struttura di dati. Contrassegna la fine della struttura dei dati e viene impostata dall'applicazione prima di richiamare la funzione che usa questa struttura di dati. La funzione non legge o scrive oltre questa dimensione. Un'applicazione deve impostare il membro dwTotalSize per indicare il numero totale di byte allocati per TAPI per restituire il contenuto della struttura.

TAPI riempie il membro dwNeedSize . Indica il numero di byte necessari per restituire tutti i dati richiesti. L'esistenza di campi di dimensioni variabili spesso rende impossibile per l'applicazione stimare le dimensioni della struttura dei dati necessarie per allocare. Questo campo restituisce il numero di byte effettivamente necessari per i dati. Questo numero potrebbe essere minore di, uguale a o maggiore di dwTotalSize e include spazio per il membro dwTotalSize stesso. Se maggiore, la struttura restituita viene riempita solo parzialmente. Se i campi richiesti dall'applicazione sono disponibili nella struttura parziale, non è necessario eseguire altre operazioni. In caso contrario, l'applicazione deve allocare almeno la dimensione di dwNeededSize e richiamare nuovamente la funzione. In genere, lo spazio sufficiente è disponibile questa volta per restituire tutte le informazioni, anche se è possibile che le dimensioni possano essere aumentate di nuovo.

TAPI riempie il membro dwUsedSize se restituisce i dati all'applicazione per indicare le dimensioni effettive, in byte, della parte della struttura di dati che contiene dati utili. Se, ad esempio, una struttura allocata era troppo piccola e il campo troncato è un campo di dimensioni variabile, dwNeedSize è maggiore di dwTotalSize e il campo troncato viene lasciato vuoto. Il membro dwUsedSize potrebbe quindi essere minore di dwTotalSize. I valori dei campi parziali non vengono restituiti.

Seguendo questa intestazione è la parte fissa della struttura dei dati. Contiene campi regolari e coppie di dimensioni/offset che descrivono i campi variabili effettivi. Il campo offset contiene l'offset in byte del campo di dimensioni variabile dall'inizio del record. Il campo dimensioni contiene le dimensioni in byte del campo di dimensioni variabile. Se un campo di dimensioni variabile è vuoto, il campo dimensione è zero e l'offset è impostato su zero. Campi variamente ridimensionati che verranno troncati se le dimensioni totali della struttura non sono sufficienti sono vuote. Vale a dire, il campo delle dimensioni è impostato su zero e l'offset è impostato su zero. I campi di dimensione variabile seguono i campi fissi.

Se il provider di servizi deve compilare un membro della variabile, TAPI inizializza le dimensioni e i membri di offset corrispondenti a zero. Se il provider di servizi compila il membro della variabile, deve impostare le dimensioni e i membri di offset corrispondenti su valori appropriati, inclusi dwUsedSize e dwNeedSize se imposta i membri delle variabili. Il provider di servizi non deve troncare un membro della variabile per renderlo adatto allo spazio disponibile.

Il provider di servizi deve avviare i membri delle variabili immediatamente dopo i membri fissi della struttura e lasciare qualsiasi spazio aggiuntivo alla fine della memoria allocata in modo che TAPI possa usarlo per i membri a lunghezza variabile. Può posizionare i membri della variabile in qualsiasi ordine, ma i membri devono essere contigui.