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 aux pointeurs dimensionnés et les tableaux multidimensionnels ou uniques.
[ size_is(limited-expression-list) ]
Paramètres
-
limited-expression-list
-
Spécifie une ou plusieurs expressions de langage C. Chaque expression prend la valeur d’un entier non négatif qui représente la quantité de mémoire allouée à un pointeur dimensionné ou à un tableau. Dans le cas d’un tableau, spécifie une expression unique qui représente la taille d’allocation, dans les é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 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 statiquement. Pour plus d’informations sur l’utilisation de l’attribut [size_is] avec plusieurs niveaux de pointeurs pour permettre à un serveur de retourner un tableau dynamique de données à 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 fixes. L’attribut [max_is] spécifie l’index de tableau valide maximal. Par conséquent, la spécification de [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 marque de fin NULL de la chaîne d’entrée. Tous les autres tableaux conformes à 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. Lorsque vous le faites, 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 exemple, votre client peut passer un paramètre [in,out] à un serveur et spécifier une allocation de mémoire volumineuse avec [size_is], même s’il spécifie un petit nombre d’éléments de données à transmettre avec [length_is]. Cela permet au serveur de remplir le tableau avec plus de données qu’il n’a reçues, qu’il peut ensuite renvoyer au client.
En général, il n’est pas utile de spécifier les paramètres [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]. Elle créerait une surcharge supplémentaire lors du marshaling de paramètres. Si les valeurs de [size_is] et [length_is] sont toujours identiques, 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