size_is (attribut)
Utilisez l’attribut [size_is] pour spécifier la taille de la mémoire, dans les éléments, allouée pour les pointeurs dimensionnés, les pointeurs dimensionnés vers des pointeurs dimensionnés et les tableaux monodimensionnels ou multidimensionnels.
[ size_is(limited-expression-list) ]
Paramètres
-
limited-expression-list
-
Spécifie une ou plusieurs expressions en langage C. Chaque expression correspond à un entier non négatif qui représente la quantité de mémoire allouée à un pointeur de taille ou à un tableau. Dans le cas d’un tableau, spécifie une expression unique qui représente la taille d’allocation, en éléments, de la première dimension de ce tableau. Le compilateur MIDL prend en charge les expressions conditionnelles, les expressions logiques, les expressions relationnelles et les expressions arithmétiques. MIDL n’autorise pas les appels de fonction dans les expressions et n’autorise pas les opérateurs d’incrémentation et de décrémentation. Utilisez des virgules comme espaces réservés pour les paramètres implicites ou pour séparer plusieurs expressions.
Notes
Si vous utilisez l’attribut [size_is] pour allouer de la mémoire pour un tableau multidimensionnel et que vous utilisez la notation de tableau [ ] , gardez à l’esprit que seule la première dimension d’un tableau multidimensionnel peut être déterminée dynamiquement au moment de l’exécution. Les autres dimensions doivent être spécifiées de manière statique. Pour plus d’informations sur l’utilisation de l’attribut [size_is] avec plusieurs niveaux de pointeurs pour permettre à un serveur de renvoyer un tableau de données de taille dynamique à un client, comme illustré dans l’exemple Proc7, consultez Plusieurs niveaux de pointeurs.
Vous pouvez utiliser [size_is] ou max_is (mais pas les deux dans la même liste d’attributs) pour spécifier la taille d’un tableau dont les limites supérieures sont déterminées au moment de l’exécution. Notez toutefois que l’attribut [size_is] ne peut pas être utilisé sur les dimensions de tableau qui sont fixes. L’attribut [max_is] spécifie l’index de tableau valide maximal. Par conséquent, spécifier [size_is(n)] équivaut à spécifier [max_is(n-1)].
Un paramètre [ in] ou [in, out] conformant-array avec l’attribut [ string] n’a pas besoin de l’attribut [size_is] ou [max_is]. Dans ce cas, la taille de l’allocation est déterminée à partir de la terminaison NULL de la chaîne d’entrée. Tous les autres tableaux conformes avec l’attribut [string] doivent avoir un attribut [size_is] ou [max_is].
Bien qu’il soit légal d’utiliser l’attribut [size_is] avec une constante, cela est inefficace et inutile. Par exemple, utilisez un tableau de taille fixe :
HRESULT Proc3([in] short Arr[MAX_SIZE]);
plutôt que :
// legal but marshaling code is much slower
HRESULT Proc3([in size_is(MAX_SIZE)] short Arr[] );
Vous pouvez utiliser les attributs [size_is] et [length_is] ensemble. Dans ce cas, l’attribut [size_is] contrôle la quantité de mémoire allouée pour les données. L’attribut [length_is] spécifie le nombre d’éléments transmis. La quantité de mémoire spécifiée par les attributs [size_is] et [length_is] n’a pas besoin d’être identique. Par instance, votre client peut passer un paramètre [in,out] à un serveur et spécifier une allocation de mémoire importante avec [size_is], même s’il spécifie un petit nombre d’éléments de données à passer avec [length_is]. Cela permet au serveur de remplir le tableau avec plus de données qu’il n’en a reçues, qu’il peut ensuite renvoyer au client.
En général, il n’est pas utile de spécifier à la fois [size_is] et [length_is] sur les paramètres [in] ou [out]. Dans les deux cas, [size_is] contrôle l’allocation de mémoire. Votre application peut utiliser [size_is] pour allouer plus d’éléments de tableau qu’elle ne transmet (comme spécifié par [length_is]). Toutefois, cela serait inefficace. Il serait également inefficace de spécifier des valeurs identiques pour [size_is] et [length_is]. Cela créerait une surcharge supplémentaire pendant le marshaling des paramètres. Si les valeurs de [size_is] et [length_is] sont toujours les mêmes, omettez l’attribut [length_is].
Exemples
HRESULT Proc1(
[in] short m;
[in, size_is(m)] short a[]); // If m = 10, a[10]
HRESULT Proc2(
[in] short m;
[in, size_is(m)] short b[][20]); // If m = 10, b[10][20]
HRESULT Proc3(
[in] short m;
[size_is(m)] short * pshort); /* Specifies a pointer
to an m-sized block of shorts */
HRESULT Proc4(
[in] short m;
[size_is( , m)] short ** ppshort); /* Specifies a pointer
to a pointer to an m-sized
block of shorts */
HRESULT Proc5(
[in] short m;
[size_is(m ,)] short ** ppshort); /* Specifies an
m-sized block of pointers
to shorts */
HRESULT Proc6(
[in] short m;
[in] short n;
[size_is(m,n)] short ** ppshort); /* Specifies a pointer to an
m-sized block of pointers, each
of which points to an n-sized
block of shorts. m associates with
the pointer closeest to the identifer
it decorates. n associates with rest.*/
HRESULT Proc7(
[out] long * pSize,
[out, size_is( , *pSize)] my_type ** ppMyType); /* Specifies a pointer
to a sized pointer,
which points to a block
of my_types, whose size is
unknown when the stub
calls the server. */
Voir aussi