WS_UNION_DESCRIPTION structure (webservices.h)

Article
08/27/2023

Informations sur les choix au sein d’un type d’union. Il est utilisé avec WS_UNION_TYPE.

Syntaxe

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;

Membres

size

Taille en octets de la structure.

alignment

Exigence d’alignement de la structure. Il doit s’agir d’une puissance de deux entre 1 et 8.

fields

Tableau de pointeurs vers les descriptions des champs de l’union.

Consultez la section Remarques pour plus d’informations sur l’ordre des champs de ce tableau.

fieldCount

Nombre de champs dans le tableau de champs. Toute partie de la structure qui n’est pas représentée par un champ sera laissée non initialisée. Les descriptions de champs peuvent faire référence au même décalage de la structure (par exemple, s’ils font tous partie d’une seule union).

enumOffset

Décalage du champ d’énumération qui contrôle le choix sélectionné dans l’union. La taille du champ est supposée être la taille d’une énumération (entier signé 32 bits).

noneEnumValue

Cette valeur correspond à la valeur d’énumération utilisée quand aucun des choix n’est actuellement défini. Ce champ est utilisé uniquement lorsque le champ est facultatif (WS_FIELD_OPTIONAL a été spécifié).

valueIndices

Ce tableau facultatif fournit des informations qui peuvent améliorer les performances de la recherche de champs de l’union par élément ou par valeur d’énumération. Ce tableau peut avoir la valeur NULL, auquel cas une recherche O(n) est utilisée, ce qui peut être suffisant pour un petit nombre de champs.

Si la valeur n’est pas NULL, les conditions suivantes doivent être remplies :

Le tableau de champs doit être trié par élément, dans l’ordre croissant. Lors de la comparaison d’un élément, l’espace de noms doit d’abord être comparé, puis le nom local. Chacun des noms doit être comparé en effectuant une comparaison à l’échelle des octets de la chaîne utf-8. Le champ qui utilise WS_ANY_ELEMENT_FIELD_MAPPING, le cas échéant, doit toujours être le dernier dans le tableau de champs.
Le tableau valueIndices pointe vers un tableau qui contient des éléments fieldCount. Le tableau valueIndices fournit les index des éléments du tableau de champs comme s’ils étaient triés par valeur dans l’ordre croissant.

Remarques

Cette description suppose une structure qui contient à la fois la valeur de sélecteur (valeur énumérée entière) et une union qui contient un champ qui correspond à chacun des choix possibles, par exemple :

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

Les exemples suivants illustrent l’initialisation d’une description d’union pour l’exemple précédent. Cet exemple remplit le champ nameIndices, mais ce champ peut être NULL à la place.

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 = &amp;choiceAString;
fieldA.field.ns = &amp;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 = &amp;choiceBString;
fieldB.field.ns = &amp;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[] =
{
    &amp;fieldA, // "http://example.com/a", "choiceA"
    &amp;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;

Les éléments ci-dessus permettent à l’un des éléments suivants d’apparaître :


&lt;choiceA xmlns="http://example.com/a"&gt;123&lt;/choiceA&gt;
&lt;choiceB xmlns="http://example.com/b"&gt;hello&lt;/choiceB&gt;

Voici un exemple de définition de valeurs :

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;

Voici la grammaire décrivant l’ordre des WS_FIELD_DESCRIPTION qui constituent un WS_UNION_DESCRIPTION. L’ordre est défini en fonction du champ de mappage du 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

Les WS_ELEMENT_FIELD_MAPPING et WS_REPEATING_ELEMENT_FIELD_MAPPING représentent les choix d’éléments et leurs champs correspondants dans l’union.

Le WS_ANY_ELEMENT_FIELD_MAPPING est le champ utilisé quand aucun des autres éléments n’a été mis en correspondance.

Les restrictions suivantes s’appliquent aux descriptions des champs :

WS_REPEATING_ELEMENT_FIELD_MAPPING ne peut être utilisé que lorsqu’un nom d’élément wrapper et un espace de noms ont été spécifiés.
WS_FIELD_OPTIONAL ne peut pas être utilisé.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau uniquement]
En-tête	webservices.h

Partager via