unique attribute
The [unique] attribute specifies a unique pointer.
pointer_default(unique)
typedef [ unique [[ , type-attribute-list ]] ] type-specifier declarator-list;
typedef struct-or-union-declarator
{
[ unique [[ , field-attribute-list ]] ] type-specifier declarator-list;
...}
[ unique [[ , function-attribute-list ]] ] type-specifier ptr-decl function-name(
[[ [ parameter-attribute-list ] ]] type-specifier [[declarator]]
, ...);
[[ [ function-attribute-list ] ]] type-specifier [[ptr-decl]] function-name(
[ unique [[ , parameter-attribute-list ]] ] type-specifier [[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 attribute [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, 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 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.
-
struct-or-union-declarator
-
field-attribute-list
-
Specifies zero or more field attributes that apply to the structure member, 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 [unique] 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
Pointer attributes 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 unique pointer has the following characteristics:
- Can have the value NULL.
- Can change during a call from NULL to non-NULL, from non-NULL to NULL, or from one non-NULL value to another.
- Can allocate new memory on the client. When the unique pointer changes from NULL to non-NULL, data returned from the server is written into new storage.
- Can use existing memory on the client without allocating new memory. When a unique pointer changes during a call from one non-NULL value to another, the pointer is assumed to point to a data object of the same type. Data returned from the server is written into existing storage specified by the value of the unique pointer before the call.
- Can orphan memory on the client. Memory referenced by a non-NULL unique pointer may never be freed if the unique pointer changes to NULL during a call and the client does not have another means of dereferencing the storage.
- Does not cause aliasing. Like storage pointed to by a reference pointer, storage pointed to by a unique pointer cannot be reached from any other name in the function.
The stubs call the user-supplied memory-management functions midl_user_allocate and midl_user_free to allocate and deallocate memory required for unique pointers and their referents.
The following restrictions apply to unique pointers:
- The [unique] attribute cannot be applied to binding-handle parameters ( handle_t) and context-handle parameters.
- The [unique] attribute cannot be applied to [out]-only top-level pointer parameters (parameters that have only the [out] directional attribute).
- By default, top-level pointers in parameter lists are [ref] pointers. This is true even if the interface specifies pointer_default(unique). Top-level parameters in parameter lists must be specified with the [unique] attribute to be a unique pointer.
- Unique pointers cannot be used to describe the size of an array or union arm because unique pointers can have the value NULL. This restriction prevents the error that results if a NULL value is used as the array size or the union-arm size.
Examples
pointer_default(unique)
typedef [unique, string] unsigned char * MY_STRING_TYPE;
[unique] char * MyFunction([in, out, unique] long * plNumber);
See also