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
void Proc1(
[in,
short] m;
[in,
size_is(m)] short a[]); // if m = 10,
a[10]
void Proc2(
[in, short] m;
[in,
size_is(m)] short b[][20]); // if m =
10, b[10][20]
void Proc3(
[in,
short] m;
[size_is(m)] short * pshort); //specifies a pointer
// to an m-sized block of shorts
void Proc4(
[in,
short] m;
[size_is(,m)]
short ** ppshort); /*specifies a pointer
to a pointer to
an m-sized
block of
shorts */
void Proc5(
[in, short] m;
[size_is(m,)] short ** ppshort); /*specifies an
m-sized block of pointers to shorts */
void 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.*/
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, 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:
void Proc3([in] short Arr[MAX_SIZE]);
instead of:
// legal but marshalling code is much slower
void Proc3([in size_is(MAX_SIZE)] short Arr[] );
See Also