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