Speicherzuordnung

Anwendungen müssen Speicher für diese Daten zuweisen; TAPI und der Dienstanbieter stellen die Daten bereit. Wenn der Vorgang asynchron ist, sind die Daten erst verfügbar, wenn die asynchrone Antwortnachricht den Erfolg angibt.

Alle Datenstrukturen, die zum Übergeben von Daten zwischen der Anwendung und der TAPI verwendet werden, werden flacher. Das heißt, Datenstrukturen enthalten keine Zeiger auf Unterstrukturen, die variabel angepasste Datenkomponenten enthalten. Stattdessen müssen Datenstrukturen, die zum Übergeben variabler Datenmengen an die Anwendung verwendet werden, die folgende Metastruktur aufweisen:

  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>

Das dwTotalSize Member ist die Größe in Bytes, die dieser Datenstruktur zugeordnet ist. Sie kennzeichnet das Ende der Datenstruktur und wird von der Anwendung festgelegt, bevor sie die Funktion aufruft, die diese Datenstruktur verwendet. Die Funktion liest oder schreibt nicht über diese Größe hinaus. Eine Anwendung muss die dwTotalSize Member festlegen, um die Gesamtanzahl der für TAPI zugewiesenen Bytes anzugeben, um den Inhalt der Struktur zurückzugeben.

TAPI füllt das dwNeededSize Mitglied aus. Es gibt an, wie viele Bytes erforderlich sind, um alle angeforderten Daten zurückzugeben. Das Vorhandensein von unterschiedlich großen Feldern macht es der Anwendung oft unmöglich, die datenstrukturgröße zu schätzen, die für die Zuordnung erforderlich ist. Dieses Feld gibt die Anzahl der Bytes zurück, die für die Daten tatsächlich erforderlich sind. Diese Zahl kann kleiner als, gleich oder größer als dwTotalSizesein, und sie enthält Platz für das dwTotalSize Member selbst. Wenn dies größer ist, wird die zurückgegebene Struktur nur teilweise gefüllt. Wenn die felder, die die Anwendung benötigt, in der Teilstruktur verfügbar sind, muss nichts anderes ausgeführt werden. Andernfalls sollte die Anwendung mindestens die Größe dwNeededSize zuordnen und die Funktion erneut aufrufen. In der Regel steht genügend Platz zur Verfügung, um alle Informationen zurückzugeben, obwohl die Größe möglicherweise wieder gestiegen sein könnte.

TAPI füllt die dwUsedSize Member aus, wenn sie Daten an die Anwendung zurückgibt, um die tatsächliche Größe (in Byte) des Teils der Datenstruktur anzugeben, der nützliche Daten enthält. Wenn beispielsweise eine Struktur, die zugeordnet wurde, zu klein war und das abgeschnittene Feld ein variabel großes Feld ist, ist dwNeededSize- größer als dwTotalSize, und das abgeschnittene Feld bleibt leer. Die dwUsedSize Member kann daher kleiner als dwTotalSizesein. Partielle Feldwerte werden nicht zurückgegeben.

Nach diesem Header ist der feste Teil der Datenstruktur. Sie enthält reguläre Felder und Größen-/Offset-Paare, die die tatsächlichen variabel angepassten Felder beschreiben. Das Offsetfeld enthält den Offset in Byte des variabel großen Felds vom Anfang des Datensatzes. Das Feld "Größe" enthält die Größe in Byte des variabel angepassten Felds. Wenn ein feld mit unterschiedlicher Größe leer ist, ist das Feld für die Größe null und der Offset auf Null festgelegt. Veränderliche Größe von Feldern, die abgeschnitten werden würden, wenn die Gesamtstrukturgröße nicht ausreicht, leer bleiben. Das heißt, ihr Größenfeld ist auf Null festgelegt, und der Offset wird auf Null festgelegt. Die veränderlichen Felder folgen den festen Feldern.

Wenn der Dienstanbieter ein Variablemember ausfüllen muss, initialisiert TAPI die entsprechende Größe und versetzte Member auf Null. Wenn der Dienstanbieter das Variablemmember ausfüllt, muss er die entsprechende Größe und die entsprechenden Offsetmember auf geeignete Werte festlegen, einschließlich dwUsedSize und dwNeededSize, wenn variablen Elemente festgelegt werden. Der Dienstanbieter darf ein variables Element nicht abschneiden, damit es in den verfügbaren Platz passt.

Der Dienstanbieter muss variable Member unmittelbar nach den festen Membern der Struktur starten und am Ende des zugewiesenen Speichers zusätzlichen Speicherplatz belassen, damit TAPI sie für die Elemente mit variabler Länge verwenden kann. Sie kann die Variablenmember in beliebiger Reihenfolge platzieren, aber die Member müssen zusammenhängend sein.