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