Edit

unique attribute

  • Article

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

Specifies a MIDL 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

arrays

Arrays and Pointers

Array and Sized-Pointer Attributes

MIDL Base Types

callback

const

context_handle

enum

first_is

handle

handle_t

ignore

last_is

length_is

local

max_is

midl_user_allocate

midl_user_free

out

pointer_default

ptr

ref

size_is

string

struct

switch_type

transmit_as

union