estrutura WS_UNION_DESCRIPTION (webservices.h)

Informações sobre as opções dentro de um tipo de união. Isso é usado com WS_UNION_TYPE.

Sintaxe

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;

Membros

size

O tamanho em bytes da estrutura.

alignment

O requisito de alinhamento da estrutura. Deve ser uma potência de dois entre 1 e 8.

fields

Uma matriz de ponteiros para as descrições dos campos da união.

Consulte a seção Comentários para obter informações sobre a ordenação dos campos nesta matriz.

fieldCount

O número de campos na matriz de campos. Qualquer parte da estrutura que não é representada por um campo será deixada não inicializada. As descrições de campos podem referenciar o mesmo deslocamento da estrutura (por exemplo, se todas fizerem parte de uma única união).

enumOffset

O deslocamento do campo de enumeração que controla qual opção é selecionada dentro da união. O tamanho do campo é considerado o tamanho de uma enumeração (inteiro com sinal de 32 bits).

noneEnumValue

Esse valor corresponde ao valor de enumeração usado quando nenhuma das opções está definida no momento. Esse campo só é usado quando o campo é opcional (WS_FIELD_OPTIONAL foi especificado).

valueIndices

Essa matriz opcional fornece informações que podem melhorar o desempenho da pesquisa de campos da união por elemento ou por valor de enumeração. Essa matriz pode ser NULL, caso em que uma pesquisa de O(n) é usada, o que pode ser suficiente para um pequeno número de campos.

Se não for NULL, o seguinte deverá ser verdadeiro:

• A matriz de campos é necessária para ser classificada por elemento, em ordem crescente. Ao comparar um elemento, o namespace deve ser comparado primeiro e, em seguida, o nome local. Cada um dos nomes deve ser comparado executando uma comparação em todo o byte da cadeia de caracteres utf-8. O campo que usa WS_ANY_ELEMENT_FIELD_MAPPING, se presente, sempre deve ser o último na matriz de campos.
• A matriz valueIndices aponta para uma matriz que tem itens fieldCount. A matriz valueIndices fornece os índices dos itens na matriz de campos como se fossem classificados por valor em ordem crescente.

Comentários

Essa descrição pressupõe uma estrutura que contém o valor do seletor (um valor enumerado inteiro) e uma união que contém um campo que corresponde a cada uma das opções possíveis, por exemplo:

// 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;
};

Os exemplos a seguir ilustram a inicialização de uma descrição de união para o exemplo anterior. Este exemplo preenche o campo nameIndices, mas esse campo pode ser 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;

O acima permitiria que qualquer um dos seguintes elementos aparecesse:

<choiceA xmlns="http://example.com/a">123</choiceA>
<choiceB xmlns="http://example.com/b">hello</choiceB>

Veja a seguir um exemplo de configuração de valores:

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;

Veja a seguir a gramática que descreve a ordem dos WS_FIELD_DESCRIPTION que compõem uma WS_UNION_DESCRIPTION. A ordem é definida com base no campo de mapeamento do 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

Os WS_ELEMENT_FIELD_MAPPING e WS_REPEATING_ELEMENT_FIELD_MAPPING representam as opções de elemento e seus campos correspondentes na união.

O WS_ANY_ELEMENT_FIELD_MAPPING é o campo usado quando nenhum dos outros elementos corresponde.

As seguintes restrições se aplicam às descrições de campo:

• WS_REPEATING_ELEMENT_FIELD_MAPPING só poderá ser usado quando um namespace e um nome de elemento wrapper tiverem sido especificados.
• WS_FIELD_OPTIONAL pode não ser usado.

Requisitos