Поделиться через

структура WS_UNION_DESCRIPTION (webservices.h)

  • Статья

Сведения о вариантах в типе объединения. Используется с WS_UNION_TYPE.

Синтаксис

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;

Члены

size

Размер структуры в байтах.

alignment

Требование к выравниванию структуры. Это должно быть два значения в диапазоне от 1 до 8.

fields

Массив указателей на описания полей объединения.

Сведения о порядке полей в этом массиве см. в разделе Примечания.

fieldCount

Число полей в массиве полей. Любая часть структуры, не представленная полем, будет не инициализирована. Описания полей могут ссылаться на одно и то же смещение структуры (например, если все они являются частью единого объединения).

enumOffset

Смещение поля перечисления, которое определяет выбор, выбранный в рамках объединения. Предполагается, что размер поля равен размеру перечисления (32-разрядное целое число со знаком).

noneEnumValue

Это значение соответствует значению перечисления, которое используется, если в данный момент не задан ни один из вариантов. Это поле используется, только если поле является необязательным (WS_FIELD_OPTIONAL было указано).

valueIndices

Этот необязательный массив предоставляет сведения, которые могут повысить производительность поиска полей объединения по элементу или значению перечисления. Этот массив может иметь значение NULL, в этом случае используется подстановка O(n), которого может быть достаточно для небольшого количества полей.

Если значение не равно NULL, должно быть верно следующее:

  • Массив полей должен быть отсортирован по элементам в порядке возрастания. При сравнении элемента сначала следует сравнить пространство имен, а затем локальное имя. Каждое из имен должно быть сопоставлено путем сравнения строки utf-8 на уровне байтов. Поле, использующее WS_ANY_ELEMENT_FIELD_MAPPING, если оно имеется, всегда должно быть последним в массиве полей.
  • Массив valueIndices указывает на массив с элементами fieldCount. Массив valueIndices предоставляет индексы элементов в массиве полей, как если бы они были отсортированы по значению в порядке возрастания.

Комментарии

Это описание предполагает структуру, которая содержит как значение селектора (целочисленное перечисляемое значение), так и объединение, содержащее поле, соответствующее каждому из возможных вариантов, например:

// 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_FIELD_DESCRIPTION , составляющих WS_UNION_DESCRIPTION. Порядок определяется на основе поля сопоставления WS_FIELD_DESCRIPTION.


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 — это поле, используемое, если ни один из других элементов не совпадает.

К описаниям полей применяются следующие ограничения.

Требования

Требование Значение
Минимальная версия клиента Windows 7 [только классические приложения]
Минимальная версия сервера Windows Server 2008 R2 [только классические приложения]
Верхняя часть webservices.h