ref

pointer_default(ref)

typedef [ ref [ , type-attribute-list ] ] type-specifier declarator-list; 

typedef struct-or-union-declarator {
    [ ref [ , field-attribute-list ] ] type-specifier declarator-list;
    ...}

[ [ function-attribute-list ] ] type-specifier [ptr-decl] function-name(
    [ ref [ , parameter-attribute-list ] ] type-specifier [declarator]
    , ...
);

type-attribute-list

Specifies one or more attributes that apply to the type. Valid type attributes include handle, switch_type, transmit_as; the pointer attributes ref, unique, or ptr; and the usage attributes context_handle, string, and ignore. Separate multiple attributes with commas.

type-specifier

Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.

declarator and declarator-list

Specifies standard C declarators, such as identifiers, pointer declarators, and array declarators. For more information, see pointers and arrays. The declarator-list consists of one or more declarators separated by commas. The parameter-name identifier in the function declarator is optional.

struct-or-union-declarator

Specifies a MIDL struct or union declarator.

field-attribute-list

Specifies zero or more field attributes that apply to the structure, union member, or function parameter. Valid field attributes include first_is, last_is, length_is, max_is, size_is; the usage attributes string, ignore, and context_handle; the pointer attribute ref, unique, or ptr; and the union attribute switch_type. Separate multiple field attributes with commas.

function-attribute-list

Specifies zero or more attributes that apply to the function. Valid function attributes are callback, local; the pointer attribute ref, unique, or ptr; and the usage attributes string, ignore, and context_handle.

ptr-decl

Specifies at least one pointer declarator to which the ref attribute applies. A pointer declarator is the same as the pointer declarator used in C; it is constructed from the * designator, modifiers such as far, and the qualifier const.

function-name

Specifies the name of the remote procedure.

parameter-attribute-list

Consists of zero or more attributes appropriate for the specified parameter type. Parameter attributes can take the directional attributes in and out; the field attributes first_is, last_is, length_is, max_is, size_is, and switch_type; the pointer attribute ref, unique, or ptr; and the usage attributes context_handle and string. The usage attribute ignore cannot be used as a parameter attribute. Separate multiple attributes with commas.

Example

[unique] char * GetFirstName( 
    [in, ref] char * pszFullName 
); 
 

Remarks

The ref attribute identifies a reference pointer. It is used simply to represent a level of indirection.

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.

A reference pointer has the following characteristics:

• Always points to valid storage; never has the value NULL. A reference pointer can always be dereferenced.
• Never changes during a call. A reference pointer always points to the same storage on the client before and after the call.
• Does not allocate new memory on the client. Data returned from the server is written into existing storage specified by the value of the reference pointer before the call.
• Does not cause aliasing. Storage pointed to by a reference pointer cannot be reached from any other name in the function.

A reference pointer cannot be used as the type of a pointer returned by a function.

If no attribute is specified for a top-level pointer parameter, it is treated as a reference pointer.

See Also

pointers, ptr, unique