Three Pointer Types

MIDL supports three types of pointers to accommodate a wide range of applications. The three different levels are called reference, unique, and full pointers, and are indicated by the attributes ref, unique, and ptr, respectively. The pointer classes described by these attributes are mutually exclusive.

Pointer attributes can be applied to pointers in type definitions, function return types, function parameters, members of structures or unions, or array elements.

Embedded pointers are pointers that are members of structures or unions or elements of arrays. Embedded pointers can differ from top-level pointers, depending upon directional attributes. In the in direction, embedded ref pointers are assumed to be pointing to valid storage and must not be null. This situation is recursively applicable to any ref pointers they are pointing to. In the in direction, embedded unique and full pointers may or may not be null.

Any pointer attribute placed on a parameter in the syntax of a function declaration affects only the rightmost pointer declarator for that parameter. To affect other pointer declarators, intermediate named types must be used.

Functions that return a pointer can have a pointer attribute as a function attribute. The unique and ptr attributes must be applied to function return types. Member declarations that are pointers can specify a pointer attribute as a field attribute. A pointer attribute can also be applied as a type attribute in typedef constructs.

When no pointer attribute is specified as a field or type attribute, pointer attributes are applied according to the rules for unattributed pointer declaration as follows:

In DCE-compatibility mode, pointer attributes are determined in the defining IDL file. If there is a pointer_default attribute specified in the defining interface, that attribute is used. If no pointer_default attribute is present, all unattributed pointers are full pointers.

In Microsoft-extensions mode, pointer attributes can be determined by importing IDL files and are applied in the following order:

  1. An explicit pointer attribute applied at the use site.
  2. The ref attribute, when the unattributed pointer is a top-level pointer parameter.
  3. A pointer_default attribute specified in the defining interface.
  4. A pointer_default attribute specified in the base interface.
  5. The unique attribute.

The pointer_default interface attribute specifies the default pointer attributes to be applied to a pointer declarator in a type, parameter, or return type declaration when that declaration does not have an explicit pointer attribute applied to it. The pointer_default interface attribute does not apply to an unattributed top-level pointer of a parameter, which is assumed to be ref.