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，則下列項目必須為 true：

• 欄位陣列必須依元素以遞增順序排序。 比較專案時，應該先比較命名空間，然後再比較本機名稱。 每個名稱都應該藉由執行 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是沒有任何其他專案相符時使用的欄位。

下列限制適用於欄位描述：

• 只有在 指定包裝函式專案名稱和命名空間時，才能使用WS_REPEATING_ELEMENT_FIELD_MAPPING。
• 無法使用WS_FIELD_OPTIONAL。

規格需求

需求	值
最低支援的用戶端	Windows 7 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 R2 [僅限桌面應用程式]
標頭	webservices.h