length_is attribute
The [length_is] attribute specifies the number of array elements to be transmitted. You must specify a non-negative value.
[length_is( limited-expression-list )]
Parameters
-
limited-expression-list
-
Specifies one or more C-language expressions. Each expression evaluates to an integer that represents the number of array elements to be transmitted. 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. Separate multiple expressions with commas.
Remarks
The [length_is] attribute determines the value of the array indexes corresponding to the [last_is] attribute when [last_is] is not specified. The relationship between these array indexes is as follows: length = last - first + 1.
The [length_is] attribute cannot be used at the same time as the [last_is] attribute or the [string] attribute.
To define a counted string with a [length_is] or [last_is] attribute, use a character array or pointer without the [string] attribute.
Using a constant expression with the [length_is] attribute is an inappropriate use of the attribute. It is legal, but inefficient, and will result in slower marshaling code.
You can use the [size_is] and [length_is] attributes together. When you do, the [size_is] attribute controls the amount of memory allocated for the data. The [length_is] attribute specifies how many elements are transmitted. The amount of memory specified by the [size_is] and [length_is] attributes need not be the same. For instance, your client may pass an [in, out] parameter to a server and specify a large memory allocation with [size_is], even though it specifies a small number of data elements to be passed with [length_is]. This enables the server to fill the array with more data than it received, which it can then send back to the client.
In general, it isn't useful to specify both [size_is] and [length_is] on [in] or [out] parameters. In both cases, [size_is] controls memory allocation. Your application could use [size_is] to allocate more array elements than it transmits (as specified by [length_is]). However, this would be inefficient. It would also be inefficient to specify identical values for [size_is] and [length_is]. Because it would create extra overhead during parameter marshaling. When the values of [size_is] and [length_is] are always the same, omit the [length_is] attribute.
Examples
/* counted string holding at most "size" characters */
typedef struct
{
unsigned short size;
unsigned short length;
[size_is(size), length_is(length)] char string[*];
} COUNTED_STRING_TYPE;
/* counted string holding at most 80 characters */
typedef struct
{
unsigned short length;
[length_is(length)] char string[80];
} STATIC_COUNTED_STRING_TYPE;
HRESULT Proc1(
[in] short iLength;
[in, length_is(iLength)] short asNumbers[10]);
See also