Speicherzuweisung

Anwendungen müssen Arbeitsspeicher 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 Antwortmeldung den Erfolg anzeigt.

Alle Datenstrukturen, die zum Übergeben von Daten zwischen der Anwendung und der TAPI verwendet werden, werden vereinfacht. Das heißt, Datenstrukturen enthalten keine Zeiger auf Unterstrukturen, die Datenkomponenten mit unterschiedlicher Größe 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-Element ist die Größe in Bytes, die dieser Datenstruktur zugeordnet ist. Er markiert das Ende der Datenstruktur und wird von der Anwendung festgelegt, bevor die Funktion aufgerufen wird, die diese Datenstruktur verwendet. Die Funktion liest oder schreibt nicht über diese Größe hinaus. Eine Anwendung muss den dwTotalSize-Member so festlegen, dass die Gesamtzahl der Bytes angegeben wird, die TAPI zugeordnet ist, um den Inhalt der Struktur zurückzugeben.

TAPI füllt den dwNeededSize-Member aus. Es gibt an, wie viele Bytes erforderlich sind, um alle angeforderten Daten zurückzugeben. Das Vorhandensein von unterschiedlich großen Feldern macht es für die Anwendung oft unmöglich, die größe der Datenstruktur zu schätzen, die für die Zuordnung erforderlich ist. Dieses Feld gibt die Anzahl der Bytes zurück, die tatsächlich für die Daten erforderlich sind. Diese Zahl kann kleiner, gleich oder größer als dwTotalSize sein, und sie enthält Platz für das dwTotalSize-Element selbst. Wenn sie größer ist, wird die zurückgegebene Struktur nur teilweise gefüllt. Wenn die von der Anwendung benötigten Felder in der Teilstruktur verfügbar sind, muss nichts anderes ausgeführt werden. Andernfalls sollte die Anwendung mindestens die Größe von dwNeededSize zuordnen und die Funktion erneut aufrufen. In der Regel ist dieses Mal genügend Speicherplatz verfügbar, um alle Informationen zurückzugeben, obwohl es möglich ist, dass sich die Größe wieder erhöht hat.

TAPI füllt den dwUsedSize-Member aus, wenn daten an die Anwendung zurückgegeben werden, um die tatsächliche Größe des Teils der Datenstruktur in Bytes anzugeben, der nützliche Daten enthält. Wenn z. B. eine zugeordnete Struktur zu klein war und das abgeschnittene Feld ein feld mit unterschiedlicher Größe ist, ist dwNeededSize größer als dwTotalSize, und das abgeschnittene Feld bleibt leer. Der dwUsedSize-Member kann daher kleiner als dwTotalSize sein. Partielle Feldwerte werden nicht zurückgegeben.

Nach diesem Header ist der feste Teil der Datenstruktur. Sie enthält reguläre Felder und Größen-/Offsetpaare, die die tatsächlichen Felder mit unterschiedlicher Größe beschreiben. Das Offsetfeld enthält den Offset des felds variabel dimensioniert vom Anfang des Datensatzes in Byte. Das Feld größe enthält die Größe des felds variabel dimension in Byte. Wenn ein Feld mit unterschiedlicher Größe leer ist, ist das Größenfeld null, und der Offset wird auf 0 (null) festgelegt. Felder mit unterschiedlicher Größe, die abgeschnitten würden, wenn die Gesamtstrukturgröße nicht ausreicht, bleiben leer. Das heißt, ihr Größenfeld ist auf 0 (null) und der Offset auf 0 (null) festgelegt. Die Felder mit unterschiedlicher Größe folgen den festen Feldern.

Wenn der Dienstanbieter einen Variablenmember ausfüllen muss, initialisiert TAPI die entsprechende Größe und Offsetmember auf 0 (null). Wenn der Dienstanbieter den Variablenmember ausfüllt, muss er die entsprechende Größe und die Offsetmember auf die entsprechenden Werte festlegen, einschließlich dwUsedSize und dwNeededSize , wenn er Variablenmember festlegt. Der Dienstanbieter darf einen Variablenmember nicht abschneiden, damit es in den verfügbaren Speicherplatz passt.

Der Dienstanbieter muss Variablenmember unmittelbar nach den festen Membern der Struktur starten und zusätzlichen Speicherplatz am Ende des zugeordneten Arbeitsspeichers lassen, damit TAPI ihn für die Member mit variabler Länge verwenden kann. Die Variablenmember können in beliebiger Reihenfolge platziert werden, die Member müssen jedoch zusammenhängend sein.