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

Tableaux

Attributs de champ

first_is

Fichier de définition d’interface (IDL)

Dans

last_is

length_is

max_is

min_is

out

string