out attribute

The [out] attribute identifies pointer parameters that are returned from the called procedure to the calling procedure (from the server to the client).

[ [function-attribute-list] ] type-specifier [pointer-declarator] function-name(
    [ out [ , parameter-attribute-list ] ] type-specifier [declarator]
    , ...
);

Parameters

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].

type-specifier

Specifies a base_type, struct, union, or enum type or type identifier. An optional storage specification can precede type-specifier.

pointer-declarator

Specifies zero or more pointer declarators. 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

Specifies zero or more attributes appropriate for a specified parameter type. Parameter attributes with the [out] attribute can also take the directional attribute [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.

declarator

Specifies the standard declarators, such as identifiers, pointer declarators, and array declarators. For more information, see Array and Sized-Pointer Attributes, arrays, and Arrays and Pointers. The parameter declarator in the function declarator, such as the parameter name, is optional.

Remarks

The [out] attribute indicates that a parameter that acts as a pointer and its associated data in memory are to be passed back from the called procedure to the calling procedure.

The [out] attribute must be a pointer. DCE IDL compilers require the presence of an explicit * as a pointer declarator in the parameter declaration. Microsoft IDL offers an extension that drops this requirement and allows an array or a previously defined pointer type.

A related attribute, [in], indicates that the parameter is passed from the calling procedure to the called procedure. The [in] and [out] attributes specify the direction in which the parameters are passed. A parameter can be defined as [in]-only, [out]-only, or [in, out].

An [out]-only parameter is assumed to be undefined when the remote procedure is called and memory for the object is allocated by the server. Since top-level pointer/parameters must always point to valid storage, and therefore cannot be NULL, [out] cannot be applied to top-level [unique] or [ptr] pointers. Parameters that are [unique] or [ptr] pointers must be either [in] or [in, out] parameters.

Examples

HRESULT MyFunction([out] short * pcount);

See also

arrays

MIDL Base Types

callback

const

context_handle

enum

first_is

ignore

in

last_is

length_is

local

max_is

ptr

ref

size_is

string

struct

switch_type

union

unique