Edit

Array and Sized-Pointer Attributes

  • Article

MIDL provides a rich set of features for passing arrays of data and pointers to data. You can use these attributes to specify characteristics of arrays and multiple levels of pointers.

Attribute Usage
size_is Specifies the amount of memory to be allocated for sized pointers, sized pointers to sized pointers, and single- or multidimensional arrays.
max_is The maximum value for an array index.
length_is The number of array elements to be transmitted.
first_is The index of the first array element to be transmitted.
last_is Gives the index of the last array element to be transmitted.
string Indicates that the one-dimensional char, wchar_t, byte (or equivalent) array, or the pointer to such an array, is to be handled as a string.
range Specifies a range of allowable values for arguments or fields whose values are set at runtime.

 

MIDL supports three kinds of pointers: reference pointers, unique pointers, and full pointers. These pointers are specified by the pointer attributes ref, unique, and ptr.

A pointer attribute can be applied as a type attribute; as a field attribute that applies to a structure member, union member, or parameter; or as a function attribute that applies to the function return type. The pointer attribute can also appear with the pointer_default keyword.

To allow a pointer parameter to change in value during a remote function, you must provide another level of indirection by supplying multiple pointer declarators. The explicit pointer attribute applied to the parameter affects only the rightmost pointer declarator for the parameter. When there are multiple pointer declarators in a parameter declaration, the other declarators default to the pointer attribute specified by the pointer_default attribute. To apply different pointer attributes to multiple pointer declarators, you must define intermediate types that specify the explicit pointer attributes.

Default Pointer-Attribute Values

When no pointer attribute is associated with a pointer that is a parameter, the pointer is assumed to be a ref pointer.

When no pointer attribute is associated with a pointer that is a member of a structure or union, the MIDL compiler assigns pointer attributes using the following priority rules (1 is highest):

  1. Attributes explicitly applied to the pointer type
  2. Attributes explicitly applied to the pointer parameter or member
  3. The pointer_default attribute in the IDL file that defines the type
  4. The pointer_default attribute in the IDL file that imports the type
  5. ptr (osf mode); unique (Microsoft RPC default mode)

When the IDL file is compiled in default mode, imported files can inherit pointer attributes from importing files. This feature is not available when you compile using the /osf switch. For more information, see import.

Function Return Types

A pointer returned by a function must be a unique pointer or a full pointer. The MIDL compiler reports an error if a function result is a reference pointer, either explicitly or by default. The returned pointer always indicates new storage.

Functions that return a pointer value can specify a pointer attribute as a function attribute. If a pointer attribute is not present, the function-result pointer uses the value provided as the pointer_default attribute.

Pointer Attributes in Type Definitions

When you specify a pointer attribute at the top level of a typedef statement, the specified attribute is applied to the pointer declarator, as expected. When no pointer attribute is specified, pointer declarators at the top level of a typedef statement inherit the pointer attribute type when used.

DCE IDL does not allow the same pointer attribute to be explicitly applied twice—for example, in both the typedef declaration and the parameter attribute list. When you use the default (Microsoft extensions) mode of the MIDL compiler, this constraint is relaxed.

For a discussion of using MIDL arrays and pointers in remote procedure calls, see Arrays and Pointers.