WS_UNION_DESCRIPTION-Struktur (webservices.h)

Informationen zu den Optionen innerhalb eines Union-Typs. Dies wird mit WS_UNION_TYPE verwendet.

Syntax

typedef struct _WS_UNION_DESCRIPTION {
  ULONG                      size;
  ULONG                      alignment;
  WS_UNION_FIELD_DESCRIPTION **fields;
  ULONG                      fieldCount;
  ULONG                      enumOffset;
  int                        noneEnumValue;
  ULONG                      *valueIndices;
} WS_UNION_DESCRIPTION;

Member

size

Die Größe der Struktur in Bytes.

alignment

Die Ausrichtungsanforderung der Struktur. Dies muss eine Macht von zwei zwischen 1 und 8 sein.

fields

Ein Array von Zeigern auf die Beschreibungen der Felder der Union.

Informationen zur Reihenfolge der Felder in diesem Array finden Sie im Abschnitt Hinweise.

fieldCount

Die Anzahl der Felder im Feldarray. Jeder Teil der Struktur, der nicht durch ein Feld dargestellt wird, wird nicht initialisiert. Feldbeschreibungen können auf denselben Offset der Struktur verweisen (z. B. wenn sie alle Teil einer einzelnen Union sind).

enumOffset

Der Offset des Enumerationsfelds, das steuert, welche Auswahl innerhalb der Union ausgewählt ist. Die Größe des Felds wird als größe einer Enumeration (32-Bit-Ganzzahl mit Vorzeichen) angenommen.

noneEnumValue

Dieser Wert entspricht dem Enumerationswert, der verwendet wird, wenn derzeit keine der Optionen festgelegt ist. Dieses Feld wird nur verwendet, wenn das Feld optional ist (WS_FIELD_OPTIONAL angegeben wurde).

valueIndices

Dieses optionale Array stellt Informationen bereit, die die Leistung des Nachschlagens von Feldern der Union entweder nach Element oder nach Enumerationswert verbessern können. Dieses Array kann NULL sein. In diesem Fall wird eine O(n)-Suche verwendet, die für eine kleine Anzahl von Feldern ausreichend ist.

Wenn nicht NULL ist, muss Folgendes wahr sein:

• Das Feldarray muss nach Element in aufsteigender Reihenfolge sortiert werden. Beim Vergleichen eines Elements sollte zuerst der Namespace und dann der lokale Name verglichen werden. Jeder der Namen sollte durch einen byteweiten Vergleich der utf-8-Zeichenfolge verglichen werden. Das Feld, das WS_ANY_ELEMENT_FIELD_MAPPING verwendet, sollte, sofern vorhanden, immer das letzte im Feldarray sein.
• Das ValueIndices-Array zeigt auf ein Array mit fieldCount-Elementen. Das valueIndices-Array stellt die Indizes der Elemente im Feldarray bereit, als wären sie nach Wert in aufsteigender Reihenfolge sortiert.

Hinweise

Diese Beschreibung setzt eine Struktur voraus, die sowohl den Selektorwert (einen ganzzahligen aufgezählten Wert) als auch eine Union enthält, die ein Feld enthält, das jeder der möglichen Optionen entspricht, z. B.:

// 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;
};

Die folgenden Beispiele veranschaulichen das Initialisieren einer Union-Beschreibung für das vorherige Beispiel. In diesem Beispiel wird das Feld nameIndizes ausgefüllt, aber dieses Feld könnte stattdessen NULL sein.

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;

Mit den oben genannten Elementen kann eines der folgenden Elemente angezeigt werden:

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

Es folgt ein Beispiel für das Festlegen von Werten:

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;

Im Folgenden wird die Grammatik beschrieben, die die Reihenfolge der WS_FIELD_DESCRIPTION beschreibt, die eine WS_UNION_DESCRIPTION bilden. Die Reihenfolge wird basierend auf dem Zuordnungsfeld des WS_FIELD_DESCRIPTION definiert.

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

Die WS_ELEMENT_FIELD_MAPPING und WS_REPEATING_ELEMENT_FIELD_MAPPING die Elementauswahl und die entsprechenden Felder in der Union darstellen.

Das WS_ANY_ELEMENT_FIELD_MAPPING ist das Feld, das verwendet wird, wenn keines der anderen Elemente übereinstimmt.

Die folgenden Einschränkungen gelten für die Feldbeschreibungen:

• WS_REPEATING_ELEMENT_FIELD_MAPPING können nur verwendet werden, wenn ein Wrapperelementname und -namespace angegeben wurden.
• WS_FIELD_OPTIONAL dürfen nicht verwendet werden.

Anforderungen