WS_FIELD_MAPPING énumération (webservices.h)

Article
03/08/2023

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

Syntax

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). Cette ne peut être utilisé qu’avec WS_DESCRIPTION_TYPE. syntax<br><br>struct Base<br>{<br> WS_STRUCT_DESCRIPTION* type;<br><br> // ... base fields ...<br>};<br><br>struct Derived : Base<br>{<br> // ... derived fields ...<br>};<br><br>struct Struct<br>{<br> Base* field;<br>};<br><br>Derived derived;<br>derived.type = &DerivedStructDescription;<br>Struct s;<br>s.field = &derived;<br><br><Struct><br> <field xsi:type='Derived'><br> // ... base fields ...<br> // ... derived fields ...<br> </field><br></Struct><br><br> 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 attribut unique. LocalName/ns du champ sont utilisés comme nom d’attribut XML et espace de noms. Sauf indication contraire, l’attribut doit apparaître dans le code XML. Si WS_FIELD_OPTIONAL est spécifié, l’attribut n’est pas obligatoire pour apparaître dans le code XML. Si facultatif et non présent, puis le champ est défini sur le WS_DEFAULT_VALUE, ou zéro si la valeur par défaut n’est pas spécifiée. `syntax<br><br>struct Struct<br>{<br> int field;<br>};<br><br>Struct s;<br>s.field = 1;<br><br><Struct field='1'/><br><br>` Pour ignorer l’attribut, une WS_VOID_TYPE doit être utilisée. Dans ce cas, un champ n’est pas requis dans la structure. Pour plus d’informations, consultez WS_VOID_TYPE .
`WS_ELEMENT_FIELD_MAPPING` Valeur : 2 Le champ correspond à un élément unique. Le localName/ns du champ est utilisé comme nom et espace de noms de l’élément XML. 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 obligatoire pour apparaître dans le code XML. Si facultatif et non présent, puis le champ est défini sur le WS_DEFAULT_VALUE, ou zéro si la valeur par défaut n’est pas spécifiée. `syntax<br><br>struct Struct<br>{<br> int field;<br>};<br><br>Struct s;<br>s.field = 1;<br><br><Struct><br> <field>1</field><br></Struct><br><br>` Pour ignorer l’élément, une WS_VOID_TYPE doit être utilisée. Dans ce cas, un champ n’est pas requis dans la structure. Pour plus d’informations, consultez WS_VOID_TYPE .
`WS_REPEATING_ELEMENT_FIELD_MAPPING` Valeur : 3 Le champ correspond à un ensemble d’éléments répétitifs. Le localName/ns du champ est utilisé comme élément XML nom 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 wrapper l’élément est souhaité, puis localName/ns doit avoir la valeur 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étés n’est pas 0. Un WS_DEFAULT_VALUE peut n’est pas spécifié pour ce mappage de champs. ItemLocalName et itemNs sont utilisés comme élément XML nom et espace de noms pour l’élément répétiteur. syntax<br><br>struct Struct<br>{<br> int* field;<br> ULONG fieldCount;<br>};<br><br>int values[] = { 1, 2 };<br>Struct s;<br>s.field = values;<br>s.fieldCount = 2;<br><br>// with wrapper element specified<br><Struct><br> <field><br> <item>1</item><br> <item>2</item><br> </field><br></Struct><br><br>// with no wrapper element specified<br><Struct><br> <item>1</item><br> <item>2</item><br></Struct><br> Le nombre d’éléments dans le tableau désérialisé peut être limité en spécifiant une structure de WS_ITEM_RANGE non NULL qui est partie du 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 mappe à un élément contenant du texte et des attributs (mais pas éléments enfants). `syntax<br><br>struct Struct<br>{<br> int field;<br>};<br><br>Struct s;<br>s.field = 1;<br><br><Struct>1</Struct><br><br>` 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é dans le 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 alors être spécifié. Si le type du champ n’est pas l’un des les types existants, puis WS_VOID_TYPE peuvent être utilisés pour spécifier champ d’un type et d’une taille arbitraires. Un WS_DEFAULT_VALUE peut être spécifié pour fournir la valeur pour initialiser le champ à lors de la désérialisation du champ. Si une valeur par défaut la valeur n’est pas spécifiée, puis le champ est initialisé à zéro. Le mappage de champs peut être utilisé avec WS_FIELD_OPTIONS valeur 0 uniquement. `syntax<br><br>struct Struct<br>{<br> int field;<br>};<br><br>Struct s;<br>s.field = 1;<br><br><Struct/><br><br>`
`WS_XML_ATTRIBUTE_FIELD_MAPPING` Valeur : 6 Le champ correspond à un attribut xml réservé (tel que xml:lang). Le localName du champ est utilisé pour identifier le nom de l’attribut XML. Sauf si WS_FIELD_OPTIONAL est spécifié, l’attribut doit apparaissent dans le code XML. Si WS_FIELD_OPTIONAL est spécifié, l’attribut n’est pas obligatoire pour apparaître dans le code XML. Si facultatif et non présent, puis le champ est défini sur le WS_DEFAULT_VALUE, ou zéro si la valeur par défaut n’est pas spécifiée. `syntax<br><br>struct Struct<br>{<br> WS_STRING field;<br>};<br><br>Struct s;<br>s.field = ...; // 'us-en';<br><br>// Example of xml:lang<br><Struct xml:lang='us-en'/><br><br>s.field = ...; // 'true'<br><br>// Example of xml:space<br><Struct xml:space='true'><br>`
`WS_ELEMENT_CHOICE_FIELD_MAPPING` Valeur : 7 Le champ correspond à un choix parmi un ensemble de possibles éléments. Chaque élément est mappé à l’un des champs d’une union. Chaque champ de l’union a une valeur d’énumération correspondante, qui est utilisé pour identifier le choix actuel. `syntax<br><br>// Enumeration of choices of different values<br>enum Choice<br>{<br> ChoiceA = 10,<br> ChoiceB = 20,<br> None = 0,<br>};<br><br>// Struct containing union of values, and enum 'selector'<br>struct Struct<br>{<br> Choice choice;<br> union<br> {<br> int a; // valid when choice is ChoiceA<br> WS_STRING b; // valid when choice is ChoiceB<br> } value;<br>}; <br><br>` 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 du champ et ns doivent avoir la valeur NULL. Sauf si WS_FIELD_OPTIONAL est spécifié, l’un des les éléments doivent 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 xml. Si facultatif et aucun des éléments sont présents, puis la valeur du sélecteur du champ est définie sur le valeur none de l’énumération (comme spécifié dans le champ noneEnumValue de WS_UNION_DESCRIPTION). En raison du fait que la valeur nonEnumValue est utilisé comme valeur par défaut, cette valeur de mappage ne prend pas en charge spécification d’un WS_DEFAULT_VALUE. `syntax<br><br>Struct s;<br>s.choice = ChoiceA;<br>s.value.a = 123;<br><br><Struct><br> <choiceA>123</choiceA><br></Struct><br><br>Struct S;<br>s.choice = ChoiceB;<br>s.value.b = ...; // 'hello'<br><br><Struct><br> <choiceB>hello</choiceB><br></Struct><br><br>Struct S;<br>s.choice = None;<br><br><Struct><br></Struct> <br>` Le champ correspond à un choix parmi un ensemble de possibles éléments. Chaque élément est mappé à l’un des champs d’une union. Chaque champ de l’union a une valeur d’énumération correspondante, qui est utilisé pour identifier le choix actuel. `syntax<br><br>// Enumeration of choices of different values<br>enum Choice<br>{<br> ChoiceA = 10,<br> ChoiceB = 20,<br> None = 0,<br>};<br><br>// Struct containing union of values, and enum &quot;selector&quot;<br>struct Struct<br>{<br> Choice choice;<br> union<br> {<br> int a; // valid when choice is ChoiceA<br> WS_STRING b; // valid when choice is ChoiceB<br> } value;<br>};<br>` 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 du champ et ns doivent avoir la valeur NULL. Sauf si WS_FIELD_OPTIONAL est spécifié, l’un des les éléments doivent 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 xml. Si facultatif et aucun des éléments sont présents, puis la valeur du sélecteur du champ est définie sur le valeur none de l’énumération (comme spécifié dans le champ noneEnumValue de WS_UNION_DESCRIPTION). En raison du fait que la valeur nonEnumValue est utilisé comme valeur par défaut, cette valeur de mappage ne prend pas en charge spécification d’un WS_DEFAULT_VALUE. `syntax<br><br>Struct s;<br>s.choice = ChoiceA;<br>s.value.a = 123;<br><br><Struct><br> <choiceA>123</choiceA><br></Struct><br><br>Struct S;<br>s.choice = ChoiceB;<br>s.value.b = ...; // &quot;hello&quot;<br><br><Struct><br> <choiceB>hello</choiceB><br></Struct><br><br>Struct S;<br>s.choice = None;<br><br><Struct><br></Struct><br>` La valeur du sélecteur indique lequel des champs du union sont définies. Les autres champs sont laissés non initialisés lorsque la valeur est désérialisée. Une application doit toujours consultez la valeur du sélecteur pour vérifier qu’un champ du union est accessible.
`WS_REPEATING_ELEMENT_CHOICE_FIELD_MAPPING` Valeur : 8 Le champ correspond à un ensemble répété 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. Le localName/ns du champ est utilisé comme élément XML nom 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 wrapper l’élément est souhaité, puis localName/ns doit avoir la valeur 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étés n’est pas 0. Un WS_DEFAULT_VALUE peut n’est pas spécifié pour ce mappage de champs. Les champs itemLocalName et itemNs doivent avoir la valeur NULL. Élément XML nom et espace de noms sont définis dans le WS_UNION_DESCRIPTION. syntax<br><br>struct Struct2<br>{<br> Struct* field; // see WS_UNION_DESCRIPTION for definition of Struct<br> ULONG fieldCount;<br>};<br><br>StructType values[2];<br>values[0].choice = ChoiceA;<br>values[0].values.a = 123;<br>values[1].choice = ChoiceB;<br>values[1].values.b = ...; // hello<br><br>Struct2 s2;<br>s2.field = values;<br>s2.fieldCount = 2;<br><br>// with wrapper element specified<br><Struct2><br> <field><br> <item>123</item><br> <item>hello</item><br> </field><br></Struct2><br><br>// with no wrapper element specified<br><Struct2><br> <item>123</item><br> <item>hello</item><br></Struct2><br><br> Le nombre d’éléments dans le tableau désérialisé peut être limité en spécifiant une structure de WS_ITEM_RANGE non NULL qui est partie du WS_FIELD_DESCRIPTION.
`WS_ANY_ELEMENT_FIELD_MAPPING` Valeur : 9
`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 utilisés. Cela correspond à un tableau de WS_XML_BUFFER, comme suit : `syntax<br><br>struct Struct<br>{<br> // ... known fields ...<br> WS_XML_BUFFER fields;<br> ULONG fieldCount;<br> // ... known fields ...<br>};<br><br>Struct s;<br>s.fields = ...; // { '<unknown1/>', '<unknown2/>'; }<br>s.fieldCount = 2;<br><br><Struct><br> ... known fields ...<br> <unknown1/><br> <unknown2/><br> ... known fields ...<br></Struct><br><br>` Pour ignorer les éléments, une WS_VOID_TYPE doit être utilisée. Dans ce cas, un champ n’est pas requis dans la structure. Consultez WS_VOID_TYPE pour plus d’informations. Le nombre d’éléments autorisés pendant la désérialisation peut être limité en spécifiant une structure de WS_ITEM_RANGE non NULL** qui est partie du 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é, comme suit : `syntax<br><br>struct Struct<br>{<br> // ... known fields ...<br> WS_XML_BUFFER* field;<br>};<br><br>Struct s;<br>s.field = ...; // 'text1<unknown1/>text2<unknown2/>'<br><br><Struct><br> ... known fields ...<br> text1<br> <unknown1/><br> text2<br> <unknown2/><br></Struct><br><br>` Pour ignorer les éléments, une WS_VOID_TYPE doit être utilisée. Dans ce cas, un champ n’est pas requis 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 des attributs qui n’étaient pas mappé à l’aide d’autres valeurs WS_FIELD_MAPPING . Si ce mappage de champs n’est pas spécifié, les attributs non mappés génère une erreur lors de la désérialisation. Le champ de nom du WS_FIELD_DESCRIPTION doit avoir la valeur NULL. Le champ ns du WS_FIELD_DESCRIPTION limite le espace de noms des attributs autorisés comme suit : Si le champ ns a la valeur NULL, il n’existe aucune restriction. The WS_FIELD_OTHER_NAMESPACE option de champ ne doit pas être définie dans ce Cas. Si le champ ns est non NULL et si 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 est non NULL et si 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 doit être Utilisé. Cela correspond à WS_ANY_ATTRIBUTES comme suit : `syntax<br><br>struct Struct<br>{<br> // ... known attributes ...<br> WS_ANY_ATTRIBUTES field;<br> // ... other content ...<br>};<br><br>Struct s;<br>s.field = ...; // 'unknown'/'http://example.com'/'value'<br><br><Struct <br> ... known attributes ... <br> xmlns:a='http://example.com' a:unknown='value'><br><br> ... other content ...<br></Struct><br><br>` Pour ignorer les attributs non mappés, une WS_VOID_TYPE doit être utilisée. Dans ce cas, un champ n’est pas requis 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

Le WS_FIELD_MAPPING indique comment les différentes parties du contenu XML sont mappées aux champs d’une structure. Par exemple, WS_ELEMENT_FIELD_MAPPING peut être utilisé pour mapper la valeur d’un élément enfant, et WS_ATTRIBUTE_FIELD_MAPPING peut ê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 lors de la désérialisation du code XML. (Voir Valeurs de retour des services Web Windows.)

L’ordre des WS_FIELD_DESCRIPTION au sein d’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 .

Configuration requise


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