Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
ref
id
in
int
odl
out
ptr
ref
Collapse the table of content
Expand the table of content

ref attribute

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


pointer_default(ref)

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

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

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

Parameters

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.

standard-declarator

Specifies a standard C declarator, such as an identifier, a pointer declarator, or an array declarator. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers.

declarator-list

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

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.

Remarks

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.

Examples

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

See also

arrays
Arrays and Pointers
Array and Sized-Pointer Attributes
MIDL Base Types
callback
const
context_handle
enum
first_is
handle
ignore
last_is
length_is
local
max_is
out
ptr
size_is
string
struct
switch_type
transmit_as
union
unique

 

 

Community Additions

ADD
Show:
© 2015 Microsoft