WS_FIELD_MAPPING enumeration (webservices.h)

Article
03/13/2023

Specifies how a field of a structure is represented in XML. This is used within a 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;

Constants


`WS_TYPE_ATTRIBUTE_FIELD_MAPPING` Value: 0 The field corresponds to the XML type attribute (xsi:type). This can only be used with 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> This mapping does not support specifying a WS_DEFAULT_VALUE.
`WS_ATTRIBUTE_FIELD_MAPPING` Value: 1 The field corresponds to a single attribute. The field's localName/ns are used as the XML attribute name and namespace. Unless specified, the attribute must appear in the XML. If WS_FIELD_OPTIONAL is specified, then the attribute is not required to appear in the XML. If optional and not present, then the field is set to the WS_DEFAULT_VALUE, or zero if the default value is not specified. `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>` To discard the attribute, a WS_VOID_TYPE should be used. In this case, a field is not required in the structure. See WS_VOID_TYPE for more information.
`WS_ELEMENT_FIELD_MAPPING` Value: 2 The field corresponds to a single element. The field's localName/ns are used as the XML element name and namespace. Unless specified, the element must appear in the XML. If WS_FIELD_OPTIONAL is specified, then the element is not required to appear in the XML. If optional and not present, then the field is set to the WS_DEFAULT_VALUE, or zero if the default value is not specified. `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>` To discard the element, a WS_VOID_TYPE should be used. In this case, a field is not required in the structure. See WS_VOID_TYPE for more information.
`WS_REPEATING_ELEMENT_FIELD_MAPPING` Value: 3 The field corresponds to a repeating set of elements. The field's localName/ns are used as the XML element name and namespace to use for the wrapper element (the element which is the parent of the repeating elements). If no wrapper element is desired, then both localName/ns should be NULL. If a wrapper element has been specified, the wrapper element must appear in the XML if repeating element count is not 0. A WS_DEFAULT_VALUE may not be specified for this field mapping. The itemLocalName and itemNs are used as the XML element name and namespace for the repeating element. 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> The number of elements in the deserialized array can be constrained by specifying a non-NULLWS_ITEM_RANGE structure that is part of the WS_FIELD_DESCRIPTION.
`WS_TEXT_FIELD_MAPPING` Value: 4 The field corresponds to the entire character content of the element. When this mapping is used, child elements are not allowed. This mapping is commonly used in conjunction with WS_ATTRIBUTE_FIELD_MAPPING to define a structure which maps to an element containing some text and attributes (but no child elements). `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>` This mapping does not support specifying a WS_DEFAULT_VALUE.
`WS_NO_FIELD_MAPPING` Value: 5 The field is neither serialized or deserialized. The field is ignored when serializing, and is initialized to the default value when deserializing. If the field maps to one of the existing types (for example WS_INT32_TYPE), then the type can be specified. If the type of the field is not one of the existing types, then WS_VOID_TYPE can be used to specify a field of an arbitrary type and size. A WS_DEFAULT_VALUE may be specified to provide the value to initialize the field to when deserializing the field. If a default value is not specified, then the field will be initialized to zero. The field mapping can be used with WS_FIELD_OPTIONS value of 0 only. `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` Value: 6 The field corresponds to a reserved xml attribute (such as xml:lang). The field's localName is used to identify the XML attribute name. Unless WS_FIELD_OPTIONAL is specified, the attribute must appear in the XML. If WS_FIELD_OPTIONAL is specified, then the attribute is not required to appear in the XML. If optional and not present, then the field is set to the WS_DEFAULT_VALUE, or zero if the default value is not specified. `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` Value: 7 The field corresponds to a choice among a set of possible elements. Each element maps to one of the fields of a union. Each field of the union has a corresponding enum value, which is used to identify the current choice. `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>` This field mapping must be used with WS_UNION_TYPE. The names and namespaces of the element choices are specified in the WS_UNION_DESCRIPTION. The field's localName and ns should be NULL. Unless WS_FIELD_OPTIONAL is specified, one of the elements must appear in the XML. If WS_FIELD_OPTIONAL is specified, then none of the elements are required to appear in the XML. If optional and none of the elements are present, then the field's selector value is set to the none value of the enumeration (as specified in the noneEnumValue field of the WS_UNION_DESCRIPTION). Due to the fact that the nonEnumValue is used as the default value, this mapping value does not support specifying a 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>` The field corresponds to a choice among a set of possible elements. Each element maps to one of the fields of a union. Each field of the union has a corresponding enum value, which is used to identify the current choice. `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>` This field mapping must be used with WS_UNION_TYPE. The names and namespaces of the element choices are specified in the WS_UNION_DESCRIPTION. The field's localName and ns should be NULL. Unless WS_FIELD_OPTIONAL is specified, one of the elements must appear in the XML. If WS_FIELD_OPTIONAL is specified, then none of the elements are required to appear in the XML. If optional and none of the elements are present, then the field's selector value is set to the none value of the enumeration (as specified in the noneEnumValue field of the WS_UNION_DESCRIPTION). Due to the fact that the nonEnumValue is used as the default value, this mapping value does not support specifying a 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>` The selector value indicates which of the fields of the union are set. Other fields are left uninitialized when the value is deserialized. An application should always consult the selector value to verify that a field of the union is accessible.
`WS_REPEATING_ELEMENT_CHOICE_FIELD_MAPPING` Value: 8 The field corresponds to a repeating set of element choices. Each item is represented by a union with selector value. This mapping must be used with WS_UNION_TYPE. The field's localName/ns are used as the XML element name and namespace to use for the wrapper element (the element which is the parent of the repeating elements). If no wrapper element is desired, then both localName/ns should be NULL. If a wrapper element has been specified, the wrapper element must appear in the XML if repeating element count is not 0. A WS_DEFAULT_VALUE may not be specified for this field mapping. The itemLocalName and itemNs fields must be NULL. The XML element name and namespace are defined in the 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> The number of elements in the deserialized array can be constrained by specifying a non-NULLWS_ITEM_RANGE structure that is part of the WS_FIELD_DESCRIPTION.
`WS_ANY_ELEMENT_FIELD_MAPPING` Value: 9
`WS_REPEATING_ANY_ELEMENT_FIELD_MAPPING` Value: 10 The field is used to discard or store a sequence of elements with any name and namespace. To store the elements, a WS_XML_BUFFER_TYPE should be used. This corresponds to an array of WS_XML_BUFFERs, as follows: `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>` To discard the elements, a WS_VOID_TYPE should be used. In this case, a field is not required in the structure. See WS_VOID_TYPE for more information. The number of elements allowed during deserialization can be constrained by specifying a non-NULL**WS_ITEM_RANGE structure that is part of the WS_FIELD_DESCRIPTION. This mapping does not support specifying a WS_DEFAULT_VALUE.
`WS_ANY_CONTENT_FIELD_MAPPING` Value: 11 The field is used to discard or store any remaining content (any mixture of text or elements) that occurs before the end of an element. To store the elements, a WS_XML_BUFFER_TYPE should be used, as follows: `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>` To discard the elements, a WS_VOID_TYPE should be used. In this case, a field is not required in the structure. See WS_VOID_TYPE for more information. This mapping does not support specifying a WS_DEFAULT_VALUE.
`WS_ANY_ATTRIBUTES_FIELD_MAPPING` Value: 12 The field is used to discard or store any attributes which were not mapped using other WS_FIELD_MAPPING values. If this field mapping is not specified, then unmapped attributes will cause an error when deserializing. The name field of the WS_FIELD_DESCRIPTION must be NULL. The ns field of the WS_FIELD_DESCRIPTION restricts the namespace of the attributes allowed as follows: If the ns field is NULL, then there is no restriction. The WS_FIELD_OTHER_NAMESPACE field option must be not set in this case. If the ns field is non-NULL, and the field option WS_FIELD_OTHER_NAMESPACE is not set for the field, then the attribute must have the same namespace as was specified in the ns field. If the ns field is non-NULL, and the field option WS_FIELD_OTHER_NAMESPACE is set for the field, then the attribute must have a different namespace than was specified in the ns field. To store the attributes, WS_ANY_ATTRIBUTES_TYPE should be used. This correspond to WS_ANY_ATTRIBUTES as follows: `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>` To discard the unmapped attributes, a WS_VOID_TYPE should be used. In this case, a field is not required in the structure. See WS_VOID_TYPE for more information. This mapping does not support specifying a WS_DEFAULT_VALUE.

Remarks

The WS_FIELD_MAPPING indicates how different parts of the XML content maps to the fields of a structure. For example, WS_ELEMENT_FIELD_MAPPING can be used to map the value of a child element, and WS_ATTRIBUTE_FIELD_MAPPING can be used to map an attribute. Any XML content that is read that is not explicitly mapped will cause WS_E_INVALID_FORMAT to be returned when the XML is deserialized. (See Windows Web Services Return Values.)

The order of the WS_FIELD_DESCRIPTION within a WS_STRUCT_DESCRIPTION is determined by the WS_FIELD_MAPPING value of the WS_FIELD_DESCRIPTION. See WS_STRUCT_DESCRIPTION for more information on the ordering.

Requirements

Requirement	Value
Minimum supported client	Windows 7 [desktop apps only]
Minimum supported server	Windows Server 2008 R2 [desktop apps only]
Header	webservices.h