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 transmettre des données entre l’application et TAPI sont aplatissement. 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 pas ou n’écrit pas au-delà de cette taille. Une application doit définir le membre dwTotalSize pour indiquer le nombre total d’octets alloués pour TAPI afin de retourner le contenu de la structure.

TAPI renseigne 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 la dwTotalSize membre lui-même. Si elle est plus grande, la structure retournée n’est 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 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 qui a été 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 inférieur à dwTotalSize. Les valeurs de champ partiel ne sont pas retournées.

L’en-tête suivant est 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 et le décalage correspondants membres sur zéro. Si le fournisseur de services remplit le membre de variable, il doit définir la taille et le décalage correspondants sur les valeurs appropriées, notamment dwUsedSize et dwNeededSize si elle définit des membres de variable. Le fournisseur de services ne doit pas tronquer un membre de variable pour le rendre adapté à l’espace disponible.

Le fournisseur de services doit démarrer les membres de variables immédiatement après les membres fixes de la structure et laisser un 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 la variable dans n’importe quel ordre, mais les membres doivent être contigus.