Partager via

énumération WS_FIELD_MAPPING (webservices.h)

  • Article

Spécifie la façon dont un champ d’une structure est représenté en XML. Cela est utilisé dans un WS_FIELD_DESCRIPTION.

Syntaxe

typedef enum {
  WS_TYPE_ATTRIBUTE_FIELD_MAPPING = 0,
  WS_ATTRIBUTE_FIELD_MAPPING = 1,
  WS_ELEMENT_FIELD_MAPPING = 2,
  WS_REPEATING_ELEMENT_FIELD_MAPPING = 3,
  WS_TEXT_FIELD_MAPPING = 4,
  WS_NO_FIELD_MAPPING = 5,
  WS_XML_ATTRIBUTE_FIELD_MAPPING = 6,
  WS_ELEMENT_CHOICE_FIELD_MAPPING = 7,
  WS_REPEATING_ELEMENT_CHOICE_FIELD_MAPPING = 8,
  WS_ANY_ELEMENT_FIELD_MAPPING = 9,
  WS_REPEATING_ANY_ELEMENT_FIELD_MAPPING = 10,
  WS_ANY_CONTENT_FIELD_MAPPING = 11,
  WS_ANY_ATTRIBUTES_FIELD_MAPPING = 12
} WS_FIELD_MAPPING;

Constantes

 
WS_TYPE_ATTRIBUTE_FIELD_MAPPING
Valeur : 0
Le champ correspond à l’attribut de type XML (xsi :type). Cela ne peut être utilisé qu’avec WS_DESCRIPTION_TYPE. 


Base de struct
{
    type WS_STRUCT_DESCRIPTION* ;

    // ... champs de base ...
};

struct dérivé : base
{
    // ... champs dérivés ...
};

struct Struct
{
    Champ Base* ;
};

Dérivé ;
derived.type = &DerivedStructDescription ;
Struct s ;
s.field = &dérivée ;


              <Struct>
    
              <champ xsi :type='Dérivé'>
        // ... champs de base ...
        // ... champs dérivés ...
    
              </field>

              </Struct>


Ce mappage ne prend pas en charge la spécification d’un WS_DEFAULT_VALUE.
WS_ATTRIBUTE_FIELD_MAPPING
Valeur : 1
Le champ correspond à un seul attribut.

LocalName/ns du champ est utilisé comme nom et espace de noms d’attribut XML.

Sauf indication contraire, l’attribut doit apparaître dans le code XML. Si WS_FIELD_OPTIONAL est spécifié, l’attribut n’est pas requis pour apparaître dans le code XML. Si elle est facultative et non présente, le champ est défini sur la WS_DEFAULT_VALUE, ou zéro si la valeur par défaut n’est pas spécifiée.


struct Struct
{
    champ int ;
};

Struct s ;
s.field = 1 ;


              <champ de struct='1'/>


Pour ignorer l’attribut, une WS_VOID_TYPE doit être utilisée. Dans ce cas, un champ n’est pas obligatoire dans la structure. Pour plus d’informations, consultez WS_VOID_TYPE.
WS_ELEMENT_FIELD_MAPPING
Valeur : 2
Le champ correspond à un seul élément.

LocalName/ns du champ est utilisé comme nom d’élément XML et espace de noms.

Sauf indication contraire, l’élément doit apparaître dans le code XML. Si WS_FIELD_OPTIONAL est spécifié, l’élément n’est pas requis pour apparaître dans le code XML. Si elle est facultative et non présente, le champ est défini sur la WS_DEFAULT_VALUE, ou zéro si la valeur par défaut n’est pas spécifiée.


struct Struct
{
    champ int ;
};

Struct s ;
s.field = 1 ;


              <Struct>
    
              <champ>1</field>

              </Struct>


Pour ignorer l’élément, une WS_VOID_TYPE doit être utilisée. Dans ce cas, un champ n’est pas obligatoire dans la structure. Pour plus d’informations, consultez WS_VOID_TYPE.
WS_REPEATING_ELEMENT_FIELD_MAPPING
Valeur : 3
Le champ correspond à un ensemble répétitif d’éléments.

LocalName/ns du champ est utilisé comme nom d’élément XML et espace de noms à utiliser pour l’élément wrapper (l’élément qui est le parent des éléments répétitifs). Si aucun élément wrapper n’est souhaité, localName/ns doit être NULL.

Si un élément wrapper a été spécifié, l’élément wrapper doit apparaître dans le code XML si le nombre d’éléments répétitif n’est pas 0. Un WS_DEFAULT_VALUE peut ne pas être spécifié pour ce mappage de champ.

ItemLocalName et itemNs sont utilisés comme nom et espace de noms d’élément XML pour l’élément répétitif.


struct Struct
{
    champ int* ;
    ULONG fieldCount ;
};

valeurs int[] = { 1, 2 } ;
Struct s ;
s.field = valeurs ;
s.fieldCount = 2 ;

avec l’élément wrapper spécifié

              <Struct>
    
              <champ>
        
              <élément>1</item>
        
              <élément>2</item>
    
              </field>

              </Struct>

sans élément wrapper spécifié

              <Struct>
    
              <élément>1</item>
    
              <élément>2</item>

              </Struct>


Le nombre d’éléments dans le tableau désérialisé peut être limité en spécifiant une structureWS_ITEM_RANGE NULL nonqui fait partie de la WS_FIELD_DESCRIPTION.
WS_TEXT_FIELD_MAPPING
Valeur : 4
Le champ correspond à l’intégralité du contenu de caractère de l’élément. Lorsque ce mappage est utilisé, les éléments enfants ne sont pas autorisés.

Ce mappage est couramment utilisé conjointement avec WS_ATTRIBUTE_FIELD_MAPPING pour définir une structure qui correspond à un élément contenant du texte et des attributs (mais aucun élément enfant).


struct Struct
{
    champ int ;
};

Struct s ;
s.field = 1 ;


              <Struct>1</Struct>


Ce mappage ne prend pas en charge la spécification d’un WS_DEFAULT_VALUE.
WS_NO_FIELD_MAPPING
Valeur : 5
Le champ n’est ni sérialisé ni désérialisé.

Le champ est ignoré lors de la sérialisation et est initialisé à la valeur par défaut lors de la désérialisation.

Si le champ est mappé à l’un des types existants (par exemple WS_INT32_TYPE), le type peut être spécifié. Si le type du champ n’est pas l’un des types existants, WS_VOID_TYPE pouvez être utilisé pour spécifier un champ d’un type et une taille arbitraires.

Une WS_DEFAULT_VALUE peut être spécifiée pour fournir la valeur à laquelle initialiser le champ lors de la désérialisation du champ. Si aucune valeur par défaut n’est spécifiée, le champ est initialisé sur zéro.

Le mappage de champs ne peut être utilisé qu’avec WS_FIELD_OPTIONS valeur 0.


struct Struct
{
    champ int ;
};

Struct s ;
s.field = 1 ;

Struct/><
WS_XML_ATTRIBUTE_FIELD_MAPPING
Valeur : 6
Le champ correspond à un attribut xml réservé (tel que xml :lang).

LocalName du champ est utilisé pour identifier le nom d’attribut XML.

Sauf si WS_FIELD_OPTIONAL est spécifié, l’attribut doit apparaître dans le code XML. Si WS_FIELD_OPTIONAL est spécifié, l’attribut n’est pas requis pour apparaître dans le code XML. Si elle est facultative et non présente, le champ est défini sur la WS_DEFAULT_VALUE, ou zéro si la valeur par défaut n’est pas spécifiée.


struct Struct
{
    champ WS_STRING ;
};

Struct s ;
s.field = ... ; 'us-en' ;

Exemple de xml :lang

              <Struct xml :lang='us-en'/>

s.field = ... ; 'true'

Exemple de xml :space

              <Struct xml :space='true'>
WS_ELEMENT_CHOICE_FIELD_MAPPING
Valeur : 7
Le champ correspond à un choix parmi un ensemble d’éléments possibles. Chaque élément est mappé à l’un des champs d’une union. Chaque champ de l’union a une valeur d’énumération correspondante, utilisée pour identifier le choix actuel.


Énumération des choix de différentes valeurs
choix d’énumération
{
    ChoiceA = 10,
    ChoiceB = 20,
    Aucun = 0,
};

Struct contenant l’union des valeurs, et énumération 'selector'
struct Struct
{
    Choix de choix ;
    union
    {
        int a ; valide lorsque le choix est ChoiceA
        WS_STRING b ; valide lorsque le choix est ChoiceB
    } valeur ;
};


Ce mappage de champs doit être utilisé avec WS_UNION_TYPE. Les noms et espaces de noms des choix d’éléments sont spécifiés dans le WS_UNION_DESCRIPTION. LocalName et ns du champ doivent être NULL.

Sauf si WS_FIELD_OPTIONAL est spécifié, l’un des éléments doit apparaître dans le code XML. Si WS_FIELD_OPTIONAL est spécifié, aucun des éléments n’est requis pour apparaître dans le code XML. Si elle est facultative et qu’aucun des éléments n’est présent, la valeur du sélecteur du champ est définie sur la valeur none de l’énumération (comme spécifié dans le champ noneEnumValue du WS_UNION_DESCRIPTION). En raison du fait que la valeur nonEnumValue est utilisée comme valeur par défaut, cette valeur de mappage ne prend pas en charge la spécification d’un WS_DEFAULT_VALUE.


Struct s ;
s.choice = ChoiceA ;
s.value.a = 123 ;


              <Struct>
    
              <choiceA>123</choiceA>

              </Struct>

Struct S ;
s.choice = ChoiceB ;
s.value.b = ... ; 'hello'


              <Struct>
    
              <choiceB>hello</choiceB>

              </Struct>

Struct S ;
s.choice = Aucun ;


              <Struct>

              </Struct>


Le champ correspond à un choix parmi un ensemble d’éléments possibles. Chaque élément est mappé à l’un des champs d’une union. Chaque champ de l’union a une valeur d’énumération correspondante, utilisée pour identifier le choix actuel.


Énumération des choix de différentes valeurs
choix d’énumération
{
    ChoiceA = 10,
    ChoiceB = 20,
    Aucun = 0,
};

Struct contenant l’union des valeurs et énumération " ; sélecteur&guillemet ;
struct Struct
{
    Choix de choix ;
    union
    {
        int a ; valide lorsque le choix est ChoiceA
        WS_STRING b ; valide lorsque le choix est ChoiceB
    } valeur ;
};


Ce mappage de champs doit être utilisé avec WS_UNION_TYPE. Les noms et espaces de noms des choix d’éléments sont spécifiés dans le WS_UNION_DESCRIPTION. LocalName et ns du champ doivent être NULL.

Sauf si WS_FIELD_OPTIONAL est spécifié, l’un des éléments doit apparaître dans le code XML. Si WS_FIELD_OPTIONAL est spécifié, aucun des éléments n’est requis pour apparaître dans le code XML. Si elle est facultative et qu’aucun des éléments n’est présent, la valeur du sélecteur du champ est définie sur la valeur none de l’énumération (comme spécifié dans le champ noneEnumValue du WS_UNION_DESCRIPTION). En raison du fait que la valeur nonEnumValue est utilisée comme valeur par défaut, cette valeur de mappage ne prend pas en charge la spécification d’un WS_DEFAULT_VALUE.


Struct s ;
s.choice = ChoiceA ;
s.value.a = 123 ;


              <Struct>
    
              <choiceA>123</choiceA>

              </Struct>

Struct S ;
s.choice = ChoiceB ;
s.value.b = ... ; " ; hello" ;


              <Struct>
    
              <choiceB>hello</choiceB>

              </Struct>

Struct S ;
s.choice = Aucun ;


              <Struct>

              </Struct>


La valeur du sélecteur indique quels champs de l’union sont définis. D’autres champs sont laissés non initialisés lorsque la valeur est désérialisée. Une application doit toujours consulter la valeur du sélecteur pour vérifier qu’un champ de l’union est accessible.
WS_REPEATING_ELEMENT_CHOICE_FIELD_MAPPING
Valeur : 8
Le champ correspond à un ensemble répétitif de choix d’éléments.

Chaque élément est représenté par une union avec une valeur de sélecteur. Ce mappage doit être utilisé avec WS_UNION_TYPE.

LocalName/ns du champ est utilisé comme nom d’élément XML et espace de noms à utiliser pour l’élément wrapper (l’élément qui est le parent des éléments répétitifs). Si aucun élément wrapper n’est souhaité, localName/ns doit être NULL.

Si un élément wrapper a été spécifié, l’élément wrapper doit apparaître dans le code XML si le nombre d’éléments répétitif n’est pas 0. Un WS_DEFAULT_VALUE peut ne pas être spécifié pour ce mappage de champ.

Les champs itemLocalName et itemNs doivent être NULL. Le nom et l’espace de noms de l’élément XML sont définis dans le WS_UNION_DESCRIPTION.


struct Struct2
{
    Champ Struct* ; voir WS_UNION_DESCRIPTION pour la définition de Struct
    ULONG fieldCount ;
};

Valeurs StructType[2] ;
values[0].choice = ChoiceA ;
values[0].values.a = 123 ;
values[1].choice = ChoiceB ;
values[1].values.b = ... ; Bonjour

Struct2 s2 ;
s2.field = valeurs ;
s2.fieldCount = 2 ;

avec l’élément wrapper spécifié

              <Struct2>
    
              <champ>
        
              <élément>123</item>
        
              <élément>bonjour</item>
    
              </field>

              </Struct2>

sans élément wrapper spécifié

              <Struct2>
    
              <élément>123</item>
    
              <élément>bonjour</item>

              </Struct2>


Le nombre d’éléments dans le tableau désérialisé peut être limité en spécifiant une structureWS_ITEM_RANGE NULL nonqui fait partie de la WS_FIELD_DESCRIPTION.
WS_ANY_ELEMENT_FIELD_MAPPING
Valeur : 9
TBD
WS_REPEATING_ANY_ELEMENT_FIELD_MAPPING
Valeur : 10
Le champ est utilisé pour ignorer ou stocker une séquence d’éléments avec n’importe quel nom et espace de noms.

Pour stocker les éléments, une WS_XML_BUFFER_TYPE doit être utilisée. Cela correspond à un tableau de WS_XML_BUFFERs, comme suit :


struct Struct
{
    // ... champs connus ...
    champs WS_XML_BUFFER** ;
    ULONG fieldCount ;
    // ... champs connus ...
};

Struct s ;
s.fields = ... ; { '<unknown1/>', '<unknown2/>' ; }
s.fieldCount = 2 ;


              <Struct>
    ... champs connus ...
    
              <inconnu1/>
    
              <inconnu2/>
    ... champs connus ...

              </Struct>


Pour ignorer les éléments, une WS_VOID_TYPE doit être utilisée. Dans ce cas, un champ n’est pas obligatoire dans la structure. Pour plus d’informations, consultez WS_VOID_TYPE.

Le nombre d’éléments autorisés pendant la désérialisation peut être limité en spécifiant une structureWS_ITEM_RANGE NULL nonqui fait partie de la WS_FIELD_DESCRIPTION.

Ce mappage ne prend pas en charge la spécification d’un WS_DEFAULT_VALUE.
WS_ANY_CONTENT_FIELD_MAPPING
Valeur : 11
Le champ est utilisé pour ignorer ou stocker tout contenu restant (tout mélange de texte ou d’éléments) qui se produit avant la fin d’un élément.

Pour stocker les éléments, une WS_XML_BUFFER_TYPE doit être utilisée, comme suit :


struct Struct
{
    // ... champs connus ...
    champ WS_XML_BUFFER* ;
};

Struct s ;
s.field = ... ; 'text1<unknown1/>text2<unknown2/>'


              <Struct>
    ... champs connus ...
    texte1
    
              <inconnu1/>
    texte2
    
              <inconnu2/>

              </Struct>


Pour ignorer les éléments, une WS_VOID_TYPE doit être utilisée. Dans ce cas, un champ n’est pas obligatoire dans la structure. Pour plus d’informations, consultez WS_VOID_TYPE.

Ce mappage ne prend pas en charge la spécification d’un WS_DEFAULT_VALUE.
WS_ANY_ATTRIBUTES_FIELD_MAPPING
Valeur : 12
Le champ est utilisé pour ignorer ou stocker les attributs qui n’ont pas été mappés à l’aide d’autres valeurs WS_FIELD_MAPPING.

Si ce mappage de champs n’est pas spécifié, les attributs non mappés provoquent une erreur lors de la désérialisation.

Le champ nom de l'WS_FIELD_DESCRIPTION doit être NULL .

Le champ ns du WS_FIELD_DESCRIPTION limite l’espace de noms des attributs autorisés comme suit :


  • Si le champ ns est NULL, il n’existe aucune restriction. Le
    WS_FIELD_OTHER_NAMESPACE option de champ ne doit pas être définie dans ce cas.

  • Si le champ ns n’est pasNULL et l’option de champ
    WS_FIELD_OTHER_NAMESPACE n’est pas défini pour le champ, puis
    l’attribut doit avoir le même espace de noms que celui spécifié dans le champ ns.

  • Si le champ ns n’est pasNULL et l’option de champ
    WS_FIELD_OTHER_NAMESPACE est défini pour le champ, puis le
    l’attribut doit avoir un espace de noms différent de celui spécifié
    dans le champ ns.



Pour stocker les attributs, WS_ANY_ATTRIBUTES_TYPE devez être utilisé. Cela correspond à WS_ANY_ATTRIBUTES comme suit :


struct Struct
{
    // ... attributs connus ...
    champ WS_ANY_ATTRIBUTES ;
    // ... autres contenus ...
};

Struct s ;
s.field = ... ; 'unknown'/'http://example.com'/'value'

Struct <
    ... attributs connus ... 
    xmlns :a='http://example.com' a :unknown='value'>

    ... autres contenus ...

              </Struct>


Pour ignorer les attributs non mappés, une WS_VOID_TYPE doit être utilisée. Dans ce cas, un champ n’est pas obligatoire dans la structure. Pour plus d’informations, consultez WS_VOID_TYPE.

Ce mappage ne prend pas en charge la spécification d’un WS_DEFAULT_VALUE.

Remarques

L'WS_FIELD_MAPPING indique comment différentes parties du contenu XML sont mappée aux champs d’une structure. Par exemple, WS_ELEMENT_FIELD_MAPPING pouvez être utilisé pour mapper la valeur d’un élément enfant, et WS_ATTRIBUTE_FIELD_MAPPING pouvez être utilisé pour mapper un attribut. Tout contenu XML lu qui n’est pas mappé explicitement entraîne le retour de WS_E_INVALID_FORMAT lorsque le code XML est désérialisé (voir Les services web Windows retournent des valeurs.)

L’ordre du WS_FIELD_DESCRIPTION dans un WS_STRUCT_DESCRIPTION est déterminé par la valeur WS_FIELD_MAPPING du WS_FIELD_DESCRIPTION. Pour plus d’informations sur la commande, consultez WS_STRUCT_DESCRIPTION.

Exigences

Exigence Valeur
client minimum pris en charge Windows 7 [applications de bureau uniquement]
serveur minimum pris en charge Windows Server 2008 R2 [applications de bureau uniquement]
d’en-tête webservices.h