WS_UNION_DESCRIPTION

共用体型内の選択肢に関する情報です。 これは WS_UNION_TYPE で使用されます。

この記述では、セレクター値 (整数の列挙値) と、可能な選択肢の それぞれに対応するフィールドを含む共用体の両方を持つ構造体を 想定しています。次に例を示します。

// Enumeration of choices of different values
enum Choice
{
    ChoiceA = 20,
    ChoiceB = 10,
    None = 0,
};

// Struct containing union of values, and enum "selector"
struct StructType
{
    Choice choice;
    union
    {
        int a;
        WS_STRING b;
    } value;
};

次の例は、前述の例に対する共用体の記述を初期化する方法を示しています。この例では nameIndices フィールドを設定していますが、このフィールドは代わりに NULL にすることもできます。

WS_XML_STRING choiceAString = WS_XML_STRING_VALUE("choiceA");
WS_XML_STRING choiceANs = WS_XML_STRING_VALUE("http://examples.org/a");

WS_UNION_FIELD_DESCRIPTION fieldA = { };
fieldA.value = ChoiceA;
fieldA.field.localName = &choiceAString;
fieldA.field.ns = &choiceANs;
fieldA.field.type = WS_INT32_TYPE;
fieldA.field.offset = WsOffsetOf(StructType, value.a);

WS_XML_STRING choiceBString = WS_XML_STRING_VALUE("choiceB");
WS_XML_STRING choiceBNs = WS_XML_STRING_VALUE("http://examples.org/b");

WS_UNION_FIELD_DESCRIPTION fieldB = { };
fieldB.value = ChoiceB;
fieldB.field.localName = &choiceBString;
fieldB.field.ns = &choiceBNs;
fieldB.field.type = WS_STRING_TYPE;
fieldB.field.offset = WsOffsetOf(StructType, value.b);

// Sorted by ascending element name (first ns, then localName)
WS_UNION_FIELD_DESCRIPTION* fieldsArray[] =
{
    &fieldA, // "http://example.com/a", "choiceA"
    &fieldB, // "http://example.com/b", "choiceB"
};

// Sorted by ascending enum value
ULONG valueIndices[] =
{
    1, // ChoiceB (10)
    0, // ChoiceA (20)
};

WS_UNION_DESCRIPTION unionDescription;
unionDescription.size = sizeof(StructType);
unionDescription.alignment = __alignof(StructType);
unionDescription.fields = fieldsArray;
unionDescription.fieldCount = WsCountOf(fieldsArray);
unionDescription.enumOffset = WsOffsetOf(StructType, choice);
unionDescription.noneEnumValue = None;
unionDescription.valueIndices = valueIndices;

上記により、次のいずれかの要素が出現できるようになります。

<choiceA xmlns="http://example.com/a">123</choiceA>
<choiceB xmlns="http://example.com/b">hello</choiceB>

次は、値を設定する例です。

StructType structType;

// Set ChoiceA
structType.choice = ChoiceA;
structType.value.a = 123;

// Set ChoiceB
static const WS_STRING = WS_STRING_VALUE(L"hello");
structType.choice = ChoiceB;
structType.value.b = helloString;

// Set "none" choice
structType.choice = None;

次は、WS_UNION_DESCRIPTION を構成する WS_FIELD_DESCRIPTION の順序を記述した文法です。順序は WS_FIELD_DESCRIPTION の mapping フィールドに基づいて定義されます。

Fields := ElementContentFields AnyElementField?
ElementContentFields := (ElementField | RepeatingElementField)*
ElementField := WS_ELEMENT_FIELD_MAPPING
RepeatingElementField := WS_REPEATING_ELEMENT_FIELD_MAPPING
AnyElementField := WS_ANY_ELEMENT_FIELD_MAPPING

WS_ELEMENT_FIELD_MAPPING と WS_REPEATING_ELEMENT_FIELD_MAPPING は、要素の選択肢と、共用体内の対応するフィールドを表します。

WS_ANY_ELEMENT_FIELD_MAPPING は、他のどの要素も一致しなかった場合に 使用されるフィールドです。

フィールドの記述には次の制限が適用されます。

• WS_REPEATING_ELEMENT_FIELD_MAPPING は、ラッパー要素の名前と名前空間が 指定されている場合にのみ使用できます。
• WS_FIELD_OPTIONAL は使用できません。