Edit

Share via


union attribute

The union keyword appears in functions that relate to discriminated unions.

/* Encapsulated union*/
typedef [[ [type-attribute-list] ]] union [[ struct-name ]] switch (switch-type switch-name) [[ union-name ]] 
{
  C-style-case-list 
  [[ [ field-attribute-list <> ] ]] type-specifier <> declarator-list <>;

        ...
}

/* Non-encapsulated union*/
typedef [switch_type(switch-type) [[ , type-attr-list ]] ] union [[ tag ]] 
{ 
    [ case ( limited-expr-list) ]
  [[ [ field-attribute-list ] ]] type-specifier declarator-list;
  [[ [ default ]
  [[ [ field-attribute-list ] ]] type-specifier declarator-list;
  ]]
}

Parameters

type-attribute-list

Specifies zero or more attributes that apply to the union type. Valid type attributes include [handle], [transmit_as]; the pointer attribute [unique], or [ptr]; and the usage attributes [context_handle] and [ignore]. Encapsulated unions can also have the [ref] pointer type attribute. Separate multiple attributes with commas.

struct-name

Specifies an optional tag that names the structure generated by the MIDL compiler.

switch-type

Specifies an int, char, enum type, or an identifier that resolves to one of these types.

switch-name

Specifies the name of the variable of type switch-type that acts as the union discriminant.

union-name

Specifies an optional identifier that names the union in the structure, generated by the MIDL compiler, that contains the union and the discriminant.

C-style-case-list

List of "case const-expr :"

limited-expression-list

Specifies one or more C-language expressions. The MIDL compiler supports conditional expressions, logical expressions, relational expressions, and arithmetic expressions. MIDL does not allow function invocations in expressions and does not allow increment and decrement operators. Individual expressions in the list should be separated by a comma.

field-attribute-list

Specifies zero or more field attributes that apply to the union member. 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 [unique] or [ptr]; and, for members that are nonencapsulated unions, the union attribute [switch_type]. Nonencapsulated unions can also use the [ref] pointer field attribute. Separate multiple field 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-list

One or more standard C declarators, such as identifiers, pointer declarators, and array declarators. (Function declarators and bit-field declarations are not allowed in unions that are transmitted in remote procedure calls. Except when you use the MIDL compiler switch /osf, these declarators are allowed in unions that are not transmitted.) Separate multiple declarators with commas.

tag

Specifies an optional tag.

Remarks

MIDL supports two types of discriminated unions: encapsulated unions and nonencapsulated unions. The encapsulated union is compatible with previous implementations of RPC (NCA version 1). The nonencapsulated union eliminates some of the restrictions of the encapsulated union and provides a more visible discriminant than the encapsulated union.

The encapsulated union is identified by the switch keyword and the absence of other union-related keywords.

The nonencapsulated union, also known as a union, is identified by the presence of the [switch_is] and [switch_type] keywords, which identify the discriminant and its type.

When you use [in, out] unions, be aware that changing the value of the union switch during the call can make the remote call behave differently from a local call. On return, the stubs copy the [in, out] parameter into memory that is already present on the client. When the remote procedure modifies the value of the union switch and consequently changes the data object's size, the stubs can overwrite valid memory with the [out] value. When the union switch changes the data object from a base type to a pointer type, the stubs can overwrite valid memory when they copy the pointer referent into the memory location indicated by the [in] value of a base type.

The shape of unions must be identical across platforms to ensure interconnectivity.

See also

Encapsulated Unions

Interface Definition (IDL) File

in

Nonencapsulated Unions

out

switch_is

switch_type