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

필드 배열의 필드 수입니다. 필드로 표현되지 않는 구조체의 모든 부분은 초기화되지 않은 상태로 남습니다. 필드 설명은 구조체의 동일한 오프셋을 참조할 수 있습니다(예: 모두 단일 공용 구조체의 일부인 경우).

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 사용할 수 없습니다.

요구 사항