Export (0) Print
Expand All
COM
id
in
int
odl
out
ptr
ref
Expand Minimize
1 out of 2 rated this helpful - Rate this topic

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

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

 

 

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.