size_is

[ size_is(limited-expression-list) ]

limited-expression-list

Specifies one or more C-language expressions. Each expression evaluates to a non-negative integer that represents the amount of memory allocated to a sized pointer or an array. In the case of an array, specifies a single expression that represents the maximum allocation size, in elements, of the first dimension of that array. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Use commas as placeholders for implicit parameters, or to separate multiple expressions.

Examples

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.*/
 HRESULT Proc7(
     [out] long  * pSize,
     [out, size_is( , *pSize)] BAR ** ppBar); /* specifies
            a pointer to a sized pointer, which points to a
            block of BARs, whose size is unknown when the 
            stub calls the server. */
 

Remarks

You can use the size_is attribute to specify the size of memory allocated for sized pointers, sized pointers to sized pointers, and single- or multi-dimensional arrays. However, if you are using array [ ] notation, only the first dimension of a multi-dimensional array can be determined at run time.

For more information on using the size_is attribute with multiple levels of pointers to enable a server to return a dynamically-sized array of data to a client, as shown in the example Proc7, see Multiple Levels of Pointers.

You can use either size_is or max_is (but not both in the same attribute list) to specify the size of an array whose upper bounds are determined at run time. Note, however, that the size_is attribute cannot be used on array dimensions that are fixed. The max_is attribute specifies the maximum valid array index. As a result, specifying size_is(n) is equivalent to specifying max_is(n-1).

An in or in, out conformant-array parameter with the string attribute need not have the size_is or max_is attribute. In this case, the size of the allocation is determined from the null terminator of the input string. All other conformant arrays with the string attribute must have a size_is or max_is attribute.

While it is legal to use the size_is attribute with a constant, doing so is inefficient and unnecessary. For example, use a fixed size array:

HRESULT Proc3([in] short Arr[MAX_SIZE]);
 

instead of:

// legal but marshalling code is much slower
HRESULT Proc3([in size_is(MAX_SIZE)] short Arr[] );
 

See Also

arrays, field_attributes, first_is, IDL, last_is, length_is, max_is, min_is