webservices.h) (WS_UNION_DESCRIPTION 结构

  • 项目

有关联合类型中的选项的信息。 这与 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 之间的 2 的幂。

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_UNION_DESCRIPTION的WS_FIELD_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