Allocazione di 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 non 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 di dati non contengono puntatori alle sottostruttura che contengono componenti dati di dimensioni variabili. Le strutture di 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 di 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 compila il membro dwNeededSize. Indica il numero di byte necessari per restituire tutti i dati richiesti. L'esistenza di campi di dimensioni variabili spesso rende impossibile all'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 può essere minore, uguale o maggiore di dwTotalSizee 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 di nuovo la funzione. In genere, è disponibile spazio sufficiente 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 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, dwNeededSize è maggiore di dwTotalSizee il campo troncato viene lasciato vuoto. Il membro dwUsedSize può quindi essere inferiore a dwTotalSize. I valori dei campi parziali non vengono restituiti.

L'intestazione seguente è la parte fissa della struttura dei dati. Contiene campi regolari e coppie di dimensioni/offset che descrivono i campi di dimensioni 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 variabili è vuoto, il campo size è zero e l'offset viene impostato su zero. I campi con dimensioni variabili che verrebbero troncati se le dimensioni totali della struttura non sono sufficienti vengono lasciate vuote. Ovvero, il campo delle dimensioni è impostato su zero e l'offset è impostato su zero. I campi di dimensioni variabili seguono i campi fissi.

Se il provider di servizi deve riempire un membro della variabile, TAPI inizializza le dimensioni e i membri offset corrispondenti su zero. Se il provider di servizi compila il membro della variabile, deve impostare le dimensioni e i membri di offset corrispondenti sui valori appropriati, inclusi dwUsedSize e dwNeededSize se imposta membri variabili. Il provider di servizi non deve troncare un membro della variabile per inserirlo nello spazio disponibile.

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