estructura WS_UNION_DESCRIPTION (webservices.h)

Información sobre las opciones dentro de un tipo de unión. Se usa con WS_UNION_TYPE.

Sintaxis

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;

Miembros

size

Tamaño en bytes de la estructura.

alignment

Requisito de alineación de la estructura. Debe ser una potencia de dos entre 1 y 8.

fields

Matriz de punteros a las descripciones de los campos de la unión.

Consulte la sección Comentarios para obtener información sobre el orden de los campos de esta matriz.

fieldCount

Número de campos de la matriz de campos. Cualquier parte de la estructura que no esté representada por un campo se dejará sin inicializar. Las descripciones de campos pueden hacer referencia al mismo desplazamiento de la estructura (por ejemplo, si forman parte de una sola unión).

enumOffset

Desplazamiento del campo de enumeración que controla qué opción se selecciona dentro de la unión. Se supone que el tamaño del campo es el tamaño de una enumeración (entero de 32 bits con signo).

noneEnumValue

Este valor corresponde al valor de enumeración utilizado cuando no se establece ninguna de las opciones actualmente. Este campo solo se usa cuando el campo es opcional (se especificó WS_FIELD_OPTIONAL).

valueIndices

Esta matriz opcional proporciona información que puede mejorar el rendimiento de la búsqueda de campos de la unión por elemento o por valor de enumeración. Esta matriz puede ser NULL, en cuyo caso se usa una búsqueda O(n), lo que puede ser suficiente para un número reducido de campos.

Si no es NULL, debe cumplirse lo siguiente:

• La matriz fields debe ordenarse por elemento, en orden ascendente. Al comparar un elemento, primero se debe comparar el espacio de nombres y, a continuación, el nombre local. Cada uno de los nombres se debe comparar realizando una comparación de bytes de la cadena utf-8. El campo que usa WS_ANY_ELEMENT_FIELD_MAPPING, si está presente, siempre debe ser el último en la matriz de campos.
• La matriz valueIndices apunta a una matriz que tiene elementos fieldCount. La matriz valueIndices proporciona los índices de los elementos de la matriz fields como si estuvieran ordenados por valor en orden ascendente.

Comentarios

En esta descripción se supone una estructura que contiene el valor del selector (un valor enumerado entero) y una unión que contiene un campo que corresponde a cada una de las opciones posibles, por ejemplo:

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

En los ejemplos siguientes se muestra cómo inicializar una descripción de unión para el ejemplo anterior. En este ejemplo se rellena el campo nameIndices, pero este campo podría ser NULL en su lugar.

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;

Lo anterior permitiría que aparezca cualquiera de los siguientes elementos:

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

A continuación se muestra un ejemplo de configuración 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;

A continuación se muestra la gramática que describe el orden de la WS_FIELD_DESCRIPTION que componen un WS_UNION_DESCRIPTION. El orden se define en función del campo de asignación del 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

Los WS_ELEMENT_FIELD_MAPPING y WS_REPEATING_ELEMENT_FIELD_MAPPING representan las opciones de elemento y sus campos correspondientes en la unión.

El WS_ANY_ELEMENT_FIELD_MAPPING es el campo que se usa cuando ninguno de los demás elementos coincide.

Las restricciones siguientes se aplican a las descripciones de campo:

• WS_REPEATING_ELEMENT_FIELD_MAPPING solo se puede usar cuando se ha especificado un nombre de elemento contenedor y un espacio de nombres.
• es posible que no se use WS_FIELD_OPTIONAL.

Requisitos