Share via

WS_UNION_DESCRIPTION struttura (webservices.h)

  • Articolo

Informazioni sulle scelte all'interno di un tipo di unione. Questa operazione viene usata con WS_UNION_TYPE.

Sintassi

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;

Members

size

Dimensioni in byte della struttura.

alignment

Requisito di allineamento della struttura. Questa deve essere una potenza di due tra 1 e 8.

fields

Matrice di puntatori alle descrizioni dei campi dell'unione.

Per informazioni sull'ordinamento dei campi in questa matrice, vedere la sezione Osservazioni.

fieldCount

Numero di campi nella matrice dei campi. Qualsiasi parte della struttura che non è rappresentata da un campo verrà lasciata non inizializzata. Le descrizioni dei campi possono fare riferimento allo stesso offset della struttura, ad esempio se fanno parte di una singola unione.

enumOffset

Offset del campo di enumerazione che controlla la scelta selezionata all'interno dell'unione. Si presuppone che le dimensioni del campo siano le dimensioni di un'enumerazione (intero con segno a 32 bit).

noneEnumValue

Questo valore corrisponde al valore enumerazione utilizzato quando nessuna delle scelte è attualmente impostata. Questo campo viene usato solo quando il campo è facoltativo (è stato specificato WS_FIELD_OPTIONAL ).

valueIndices

Questa matrice facoltativa fornisce informazioni che possono migliorare le prestazioni di ricerca dei campi dell'unione in base all'elemento o al valore enumerazione. Questa matrice può essere NULL, nel qual caso viene usata una ricerca O(n), che può essere sufficiente per piccoli numeri di campi.

Se non null, è necessario che sia true:

  • La matrice dei campi deve essere ordinata in base all'elemento, in ordine crescente. Quando si confronta un elemento, lo spazio dei nomi deve essere confrontato prima, quindi il nome locale. Ognuno dei nomi deve essere confrontato eseguendo un confronto a livello di byte della stringa utf-8. Il campo che usa WS_ANY_ELEMENT_FIELD_MAPPING, se presente, deve essere sempre ultimo nella matrice dei campi.
  • La matrice valueIndices punta a una matrice con elementi fieldCount. La matrice valueIndices fornisce gli indici degli elementi nella matrice dei campi come se fossero ordinati in base al valore in ordine crescente.

Commenti

Questa descrizione presuppone una struttura che contiene sia il valore del selettore (un valore enumerato intero) sia un'unione che contiene un campo che corrisponde a ognuna delle possibili scelte, ad esempio:

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

Gli esempi seguenti illustrano l'inizializzazione di una descrizione dell'unione per l'esempio precedente. In questo esempio viene compilato il campo nameIndices, ma questo campo potrebbe essere 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;

L'elemento precedente consente la visualizzazione di uno degli elementi seguenti:


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

Di seguito è riportato un esempio di impostazione dei valori:

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;

Di seguito è riportata la grammatica che descrive l'ordine del WS_FIELD_DESCRIPTION che costituiscono un WS_UNION_DESCRIPTION. L'ordine viene definito in base al campo di mapping della 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

Il WS_ELEMENT_FIELD_MAPPING e WS_REPEATING_ELEMENT_FIELD_MAPPING rappresentano le scelte degli elementi e i relativi campi corrispondenti nell'unione.

Il WS_ANY_ELEMENT_FIELD_MAPPING è il campo utilizzato quando nessuno degli altri elementi corrisponde.

Le restrizioni seguenti si applicano alle descrizioni dei campi:

Requisiti

Requisito Valore
Client minimo supportato Windows 7 [solo app desktop]
Server minimo supportato Windows Server 2008 R2 [solo app desktop]
Intestazione webservices.h