Geheugentoewijzing

Toepassingen moeten geheugen toewijzen voor deze gegevens; TAPI en de serviceprovider bieden de gegevens. Als de bewerking asynchroon is, zijn de gegevens pas beschikbaar als het asynchrone antwoordbericht aangeeft dat de bewerking is geslaagd.

Alle gegevensstructuren die worden gebruikt om gegevens door te geven tussen de toepassing en de TAPI, worden afgevlakt. Dat wil gezegd: gegevensstructuren bevatten geen aanwijzers naar substructuren die gegevensonderdelen van verschillende grootten bevatten. In plaats daarvan moeten gegevensstructuren die worden gebruikt om variabele hoeveelheden gegevens terug te geven aan de toepassing de volgende metastructuur hebben:

  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>

De dwTotalSize lid is de grootte, in bytes, die aan deze gegevensstructuur zijn toegewezen. Het markeert het einde van de gegevensstructuur en wordt ingesteld door de toepassing voordat deze de functie aanroept die gebruikmaakt van deze gegevensstructuur. De functie leest of schrijft niet verder dan deze grootte. Een toepassing moet het dwTotalSize lid instellen om het totale aantal bytes aan te geven dat is toegewezen aan TAPI om de inhoud van de structuur te retourneren.

TAPI vult het dwNeededSize lid in. Het geeft aan hoeveel bytes er nodig zijn om alle aangevraagde gegevens te retourneren. Het bestaan van velden met verschillende grootten maakt het vaak onmogelijk voor de toepassing om de grootte van de gegevensstructuur te schatten die nodig is om toe te wijzen. Dit veld retourneert het aantal bytes dat daadwerkelijk vereist is voor de gegevens. Dit getal kan kleiner zijn dan, gelijk aan of groter zijn dan dwTotalSize, en het bevat ruimte voor de dwTotalSize lid zelf. Als deze groter is, is de geretourneerde structuur slechts gedeeltelijk gevuld. Als de velden die de toepassing vereist, beschikbaar zijn in de gedeeltelijke structuur, hoeft u niets anders te doen. Anders moet de toepassing een structuur ten minste de grootte van dwNeededSize toewijzen en de functie opnieuw aanroepen. Meestal is er deze keer voldoende ruimte beschikbaar om alle informatie te retourneren, hoewel het mogelijk is dat de grootte opnieuw is toegenomen.

TAPI vult de dwUsedSize lid als deze gegevens retourneert naar de toepassing om de werkelijke grootte, in bytes, aan te geven van het gedeelte van de gegevensstructuur dat nuttige gegevens bevat. Als bijvoorbeeld een structuur die is toegewezen te klein was en het afgekapte veld een veld met een afwijkingsgrootte is, is dwNeedEdSize- groter dan dwTotalSize-en blijft het afgekapte veld leeg. Het dwUsedSize lid kan daarom kleiner zijn dan dwTotalSize. Gedeeltelijke veldwaarden worden niet geretourneerd.

Na deze header is het vaste deel van de gegevensstructuur. Het bevat reguliere velden en grootte/offsetparen die de velden met een werkelijke variantiegrootte beschrijven. Het offsetveld bevat de offset in bytes van het veld met een afwijkingsmaat vanaf het begin van de record. Het veld Grootte bevat de grootte in bytes van het veld met verschillende grootten. Als een veld met een afwijkingsgrootte leeg is, is het veld Grootte nul en wordt de offset ingesteld op nul. Velden met verschillende grootten die worden afgekapt als de totale structuurgrootte onvoldoende is, leeg blijven. Dat wil gezegd: het veld grootte is ingesteld op nul en de offset wordt ingesteld op nul. De velden met verschillende grootten volgen de vaste velden.

Als de serviceprovider een variabel lid moet vullen, initialiseert TAPI de bijbehorende grootte en offsetleden tot nul. Als de serviceprovider het variabele lid invult, moet deze de bijbehorende grootte en offsetleden instellen op de juiste waarden, waaronder dwUsedSize en dwNeedSize als er variabele leden worden ingesteld. De serviceprovider mag een variabel lid niet afkappen om deze in de beschikbare ruimte te laten passen.

De serviceprovider moet variabele leden onmiddellijk na de vaste leden van de structuur starten en eventuele extra ruimte aan het einde van het toegewezen geheugen achterlaten, zodat TAPI deze kan gebruiken voor de leden van de variabele lengte. De variabele leden kunnen in elke volgorde worden geplaatst, maar de leden moeten aaneengesloten zijn.