attribut byte_count
L’attribut ACF [byte_count] est un attribut de paramètre qui associe une taille, en octets, à la zone mémoire indiquée par le pointeur.
[ function-attribute-list ] function-name(
[byte_count(length-variable-name)] parameter-name);
...);
Paramètres
-
function-attribute-list
-
Spécifie zéro ou plusieurs attributs de fonction ACF.
-
function-name
-
Spécifie le nom de la fonction définie dans le fichier IDL. Le nom de la fonction est obligatoire.
-
length-variable-name
-
Spécifie le nom du paramètre [in]-only qui spécifie la taille, en octets, de la zone mémoire référencée par parameter-name.
-
parameter-name
-
Spécifie le nom du paramètre de pointeur [out]-only défini dans le fichier IDL.
Notes
L’attribut ACF [byte_count] représente une extension Microsoft à DCE IDL. Par conséquent, cet attribut n’est pas disponible lorsque vous utilisez le commutateur de compilateur MIDL /osf.
Notes
L’attribut [nombre d’octets] n’est plus pris en charge dans la syntaxe NDR64 en raison de la difficulté à estimer la taille requise pour tous les paramètres [out].
La mémoire référencée par le paramètre pointeur est contiguë et n’est pas allouée ou libérée par les stubs du client. Cette fonctionnalité de l’attribut [byte_count] vous permet de créer une zone de mémoire tampon persistante dans la mémoire du client qui peut être réutilisée pendant plusieurs appels à la procédure distante.
La possibilité de désactiver l’allocation de mémoire stub client vous permet d’optimiser l’application. Par exemple, l’attribut [byte_count] peut être utilisé par les fonctions de fournisseur de services qui utilisent Microsoft RPC. Lorsqu’une application utilisateur appelle l’API du fournisseur de services et envoie un pointeur vers une mémoire tampon, le fournisseur de services peut passer le pointeur de mémoire tampon à la fonction distante. Le fournisseur de services peut réutiliser la mémoire tampon pendant plusieurs appels distants sans forcer l’utilisateur à réallouer la zone mémoire.
La zone mémoire peut contenir des structures de données complexes qui se composent de plusieurs pointeurs. Étant donné que la zone de mémoire est contiguë, l’application n’a pas besoin d’effectuer plusieurs appels pour libérer individuellement chaque pointeur et chaque structure. Au lieu de cela, il peut allouer ou libérer la zone mémoire avec un appel à l’allocation de mémoire ou à la routine gratuite.
La mémoire tampon doit être un paramètre [out]-only, tandis que la longueur de la mémoire tampon en octets doit être un paramètre [in]-only.
Spécifiez une mémoire tampon suffisamment grande pour contenir tous les paramètres [out]. En raison du remplissage masqué, utilisez des surestimations plutôt que des nombres exacts. Par exemple, les pointeurs de 4 octets sont démarssés sur une limite alignée sur 4 octets sur des plateformes 32 bits et des pointeurs de 8 octets sur une limite de 8 octets sur les plateformes 64 bits. Par conséquent, le remplissage d’alignement que les stubs effectueront doit être pris en compte dans l’espace de la mémoire tampon. En outre, les niveaux d’empaquetage utilisés pendant la compilation en langage C peuvent varier. Utilisez une valeur de nombre d’octets qui prend en compte les octets de compression supplémentaires ajoutés pour le niveau de compression utilisé lors de la compilation en langage C. Une pratique sûre qui couvre à la fois les plateformes 32 bits et les plateformes 64 bits consiste à supposer que chaque objet entrant dans le bloc de mémoire volumineux commence à une adresse qui est un multiple de 8.
Exemples
/* IDL file */
HRESULT proc1([in] unsigned long length,
[out] struct my_struct * pMyStruct);
/* ACF file */
proc1([byte_count(length)] pMyStruct);
Voir aussi