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 の間の 2 つの累乗である必要があります。

fields

共用体のフィールドの説明へのポインターの配列。

この配列内のフィールドの順序については、「解説」セクションを参照してください。

fieldCount

フィールド配列内のフィールドの数。 フィールドによって表されない構造体の任意の部分は、初期化されていないままになります。 フィールドの説明は、構造体の同じオフセットを参照できます (たとえば、それらがすべて 1 つの共用体の一部である場合)。

enumOffset

共用体内で選択される選択肢を制御する列挙フィールドのオフセット。 フィールドのサイズは、列挙体のサイズ (32 ビット符号付き整数) であると見なされます。

noneEnumValue

この値は、現在どの選択肢も設定されていない場合に使用される列挙値に対応します。 このフィールドは、フィールドが省略可能な場合にのみ使用されます (WS_FIELD_OPTIONAL が指定されています)。

valueIndices

この省略可能な配列は、要素または列挙型の値によって共用体のフィールドを検索するパフォーマンスを向上させる情報を提供します。 この配列は NULL の場合があります。この場合、O(n) ルックアップが使用され、少数のフィールドで十分な場合があります。

NULL 以外の場合は、次の条件を満たす必要があります。

• fields 配列は、要素で昇順に並べ替える必要があります。 要素を比較するときは、最初に名前空間を比較し、次にローカル名を比較する必要があります。 各名前は、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 [デスクトップ アプリのみ]
Header	webservices.h