Alokacja pamięci

Aplikacje muszą przydzielić pamięć dla tych danych; Interfejs TAPI i dostawca usług udostępniają dane. Jeśli operacja jest asynchroniczna, dane nie są dostępne, dopóki komunikat odpowiedzi asynchronicznej nie wskazuje powodzenia.

Wszystkie struktury danych używane do przekazywania danych między aplikacją a interfejsem TAPI są spłaszczone. Oznacza to, że struktury danych nie zawierają wskaźników do podstruktur, które zawierają niezmiennie rozmiar składników danych. Zamiast tego struktury danych używane do przekazywania zmiennych ilości danych z powrotem do aplikacji muszą mieć następującą metastrukturę:

  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>

Element dwTotalSize jest rozmiarem w bajtach przydzielonym do tej struktury danych. Oznacza ona koniec struktury danych i jest ustawiana przez aplikację przed wywołaniem funkcji korzystającej z tej struktury danych. Funkcja nie odczytuje ani nie zapisuje poza tym rozmiarem. Aplikacja musi ustawić element członkowski dwTotalSize, aby wskazać łączną liczbę bajtów przydzielonych interfejsowi TAPI w celu zwrócenia zawartości struktury.

Interfejs TAPI wypełnia element członkowski dwNeededSize. Wskazuje, ile bajtów jest wymaganych do zwrócenia wszystkich żądanych danych. Istnienie niezmiennych pól często uniemożliwia aplikacji oszacowanie rozmiaru struktury danych wymaganego do przydzielenia. To pole zwraca liczbę bajtów, które są rzeczywiście wymagane dla danych. Ta liczba może być mniejsza niż, równa lub większa niż dwTotalSizei zawiera miejsce dla samego elementu członkowskiego dwTotalSize. Jeśli jest większy, zwracana struktura jest wypełniana tylko częściowo. Jeśli pola wymagane przez aplikację są dostępne w częściowej strukturze, nic innego nie należy robić. W przeciwnym razie aplikacja powinna przydzielić strukturę co najmniej o rozmiarze dwNeededSize i wywołać funkcję ponownie. Zazwyczaj wystarczająca ilość miejsca jest dostępna tym razem, aby zwrócić wszystkie informacje, chociaż możliwe, że rozmiar mógł zostać ponownie zwiększony.

Interfejs TAPI wypełnia element członkowski dwUsedSize, jeśli zwraca dane do aplikacji, aby wskazać rzeczywisty rozmiar w bajtach części struktury danych zawierającej przydatne dane. Jeśli na przykład struktura przydzielona była zbyt mała, a obcięte pole jest polem o niezmiennym rozmiarze, dwNeededSize jest większy niż dwTotalSize, a obcięte pole pozostanie puste. Dlatego element członkowski dwUsedSize może być mniejszy niż dwTotalSize. Częściowe wartości pól nie są zwracane.

Po tym nagłówku jest stałą częścią struktury danych. Zawiera regularne pola i pary rozmiaru/przesunięcia, które opisują rzeczywiste pola o niezmiennym rozmiarze. Pole przesunięcia zawiera przesunięcie w bajtach pola o zmiennym rozmiarze od początku rekordu. Pole rozmiaru zawiera rozmiar w bajtach pola o niezmiennym rozmiarze. Jeśli pole o niezmiennym rozmiarze jest puste, pole rozmiaru wynosi zero, a przesunięcie jest ustawione na zero. Pola o niezmiennym rozmiarze, które byłyby obcięte, jeśli całkowity rozmiar struktury jest niewystarczający, są puste. Oznacza to, że ich pole rozmiaru jest ustawione na zero, a przesunięcie jest ustawione na zero. Pola o niezmiennym rozmiarze są zgodne ze stałymi polami.

Jeśli dostawca usług musi wypełnić element członkowski zmiennej, interfejs TAPI inicjuje odpowiedni rozmiar i zrównoważy elementy członkowskie do zera. Jeśli dostawca usług wypełnia element członkowski zmiennej, musi ustawić odpowiedni rozmiar i przesunięcie elementów członkowskich na odpowiednie wartości, w tym dwUsedSize i dwNeededSize, jeśli ustawia składowe zmiennych. Dostawca usług nie może obcinać elementu członkowskiego zmiennej, aby dopasować go do dostępnego miejsca.

Dostawca usług musi uruchamiać elementy członkowskie zmiennych natychmiast po stałych elementach członkowskich struktury i pozostawić dodatkowe miejsce na końcu przydzielonej pamięci, aby interfejs TAPI mógł go używać dla składowych o zmiennej długości. Może umieścić zmienne elementy członkowskie w dowolnej kolejności, ale składowe muszą być ciągłe.