Allocation de mémoire

Les applications doivent allouer de la mémoire pour ces données ; TAPI et le fournisseur de services fournissent les données. Si l’opération est asynchrone, les données ne sont pas disponibles tant que le message de réponse asynchrone n’indique pas la réussite.

Toutes les structures de données utilisées pour passer des données entre l’application et l’I TAPI sont aplatis. Autrement dit, les structures de données ne contiennent pas de pointeurs vers des sous-structures qui contiennent des composants de données de taille variable. Au lieu de cela, les structures de données utilisées pour transmettre des quantités variables de données à l’application doivent avoir la métastructure suivante :

  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>

Le membre dwTotalSize est la taille, en octets, allouée à cette structure de données. Elle marque la fin de la structure de données et est définie par l’application avant d’appeler la fonction qui utilise cette structure de données. La fonction ne lit ni n’écrit au-delà de cette taille. Une application doit définir le membre dwTotalSize pour indiquer le nombre total d’octets alloués à TAPI pour retourner le contenu de la structure.

TAPI remplit le membre dwNeededSize . Il indique le nombre d’octets requis pour retourner toutes les données demandées. L’existence de champs de taille variable rend souvent impossible pour l’application d’estimer la taille de la structure de données nécessaire à l’allocation. Ce champ retourne le nombre d’octets réellement requis pour les données. Ce nombre peut être inférieur, égal à ou supérieur à dwTotalSize, et il inclut de l’espace pour le membre dwTotalSize lui-même. Si elle est plus grande, la structure retournée n’est que partiellement remplie. Si les champs requis par l’application sont disponibles dans la structure partielle, rien d’autre ne doit être fait. Sinon, l’application doit allouer une structure d’au moins la taille de dwNeededSize et appeler à nouveau la fonction. En règle générale, suffisamment d’espace est disponible cette fois pour retourner toutes les informations, bien qu’il soit possible que la taille ait augmenté à nouveau.

TAPI remplit le membre dwUsedSize s’il retourne des données à l’application pour indiquer la taille réelle, en octets, de la partie de la structure de données qui contient des données utiles. Si, par exemple, une structure allouée était trop petite et que le champ tronqué est un champ de taille variable, dwNeededSize est plus grand que dwTotalSize et le champ tronqué est laissé vide. Le membre dwUsedSize peut donc être plus petit que dwTotalSize. Les valeurs des champs partiels ne sont pas retournées.

Cet en-tête contient la partie fixe de la structure de données. Il contient des champs réguliers et des paires taille/décalage qui décrivent les champs de taille variable réelle. Le champ offset contient le décalage en octets du champ de taille variable à partir du début de l’enregistrement. Le champ taille contient la taille en octets du champ de taille variable. Si un champ de taille variable est vide, le champ de taille est égal à zéro et le décalage est défini sur zéro. Les champs de taille variable qui seraient tronqués si la taille totale de la structure est insuffisante sont laissés vides. Autrement dit, leur champ de taille est défini sur zéro et le décalage est défini sur zéro. Les champs de taille variable suivent les champs fixes.

Si le fournisseur de services doit remplir un membre de variable, TAPI initialise la taille correspondante et décaler les membres sur zéro. Si le fournisseur de services remplit le membre de variable, il doit définir les membres de taille et de décalage correspondants sur les valeurs appropriées, y compris dwUsedSize et dwNeededSize s’il définit des membres de variable. Le fournisseur de services ne doit pas tronquer un membre de variable pour qu’il s’intègre dans l’espace disponible.

Le fournisseur de services doit démarrer les membres de variable immédiatement après les membres fixes de la structure et laisser tout espace supplémentaire à la fin de la mémoire allouée afin que TAPI puisse l’utiliser pour les membres de longueur variable. Il peut placer les membres de variable dans n’importe quel ordre, mais les membres doivent être contigus.