通过

WS_FIELD_MAPPING枚举 （webservices.h）

  • 项目

指定如何在 XML 中表示结构的字段。 这在 WS_FIELD_DESCRIPTION中使用。

语法

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;

常数

 
WS_TYPE_ATTRIBUTE_FIELD_MAPPING
值：0
该字段对应于 XML 类型属性（xsi：type）。 这只能与 WS_DESCRIPTION_TYPE一起使用。 


结构基
{
    WS_STRUCT_DESCRIPTION* 类型;

    // ...基字段...
};

结构派生 ：基
{
    // ...派生字段...
};

结构结构
{
    Base* 字段;
};

派生的派生;
derived.type = &DerivedStructDescription;
结构;
s.field = &派生;


              <结构>
    
              <字段 xsi：type='Derived'>
        // ...基字段...
        // ...派生字段...
    
              </field>

              </结构>


此映射不支持指定 WS_DEFAULT_VALUE。
WS_ATTRIBUTE_FIELD_MAPPING
值：1
该字段对应于单个属性。

字段的 localName/ns 用作 XML 属性名称和命名空间。

除非指定，否则属性必须出现在 XML 中。 如果指定了 WS_FIELD_OPTIONAL，则不需要在 XML 中显示该属性。 如果可选且不存在，则字段设置为 WS_DEFAULT_VALUE;如果未指定默认值，则为零。


结构结构
{
    int 字段;
};

结构;
s.field = 1;


              <结构字段='1'/>


若要放弃属性，应使用 WS_VOID_TYPE。 在这种情况下，结构中不需要字段。 有关详细信息，请参阅 WS_VOID_TYPE。
WS_ELEMENT_FIELD_MAPPING
值：2
该字段对应于单个元素。

字段的 localName/ns 用作 XML 元素名称和命名空间。

除非指定，否则元素必须出现在 XML 中。 如果指定了 WS_FIELD_OPTIONAL，则不需要在 XML 中显示该元素。 如果可选且不存在，则字段设置为 WS_DEFAULT_VALUE;如果未指定默认值，则为零。


结构结构
{
    int 字段;
};

结构;
s.field = 1;


              <结构>
    
              <字段>1</field>

              </结构>


若要放弃该元素，应使用 WS_VOID_TYPE。 在这种情况下，结构中不需要字段。 有关详细信息，请参阅 WS_VOID_TYPE。
WS_REPEATING_ELEMENT_FIELD_MAPPING
值：3
该字段对应于一组重复的元素。

字段的 localName/ns 用作 XML 元素名称和命名空间，用于包装元素（作为重复元素的父元素）。 如果不需要包装元素，则两个 localName/ns 都应 NULL。

如果指定了包装元素，则在重复元素计数不是 0 时，包装元素必须出现在 XML 中。 不能为此字段映射指定 WS_DEFAULT_VALUE。

itemLocalName 和 itemN 用作重复元素的 XML 元素名称和命名空间。


结构结构
{
    int* 字段;
    ULONG fieldCount;
};

int values[] = { 1， 2 };
结构;
s.field = 值;
s.fieldCount = 2;

指定了包装元素

              <结构>
    
              <字段>
        
              <项>1</item>
        
              <项>2</item>
    
              </field>

              </结构>

未指定包装元素

              <结构>
    
              <项>1</item>
    
              <项>2</item>

              </结构>


可以通过指定属于 WS_FIELD_DESCRIPTION的非NULLWS_ITEM_RANGE 结构来约束反序列化数组中的元素数。
WS_TEXT_FIELD_MAPPING
值：4
该字段对应于元素的整个字符内容。 使用此映射时，不允许子元素。

此映射通常与 WS_ATTRIBUTE_FIELD_MAPPING 结合使用来定义一个结构，该结构映射到包含某些文本和属性的元素（但没有子元素）。


结构结构
{
    int 字段;
};

结构;
s.field = 1;


              <结构>1</结构>


此映射不支持指定 WS_DEFAULT_VALUE。
WS_NO_FIELD_MAPPING
值：5
字段既不序列化也不反序列化。

序列化时将忽略字段，并在反序列化时初始化为默认值。

如果字段映射到现有类型之一（例如 WS_INT32_TYPE），则可以指定该类型。 如果字段的类型不是现有类型之一，则可以使用 WS_VOID_TYPE 指定任意类型和大小的字段。

可以指定 WS_DEFAULT_VALUE，以提供在反序列化字段时要初始化字段的值。 如果未指定默认值，则字段将初始化为零。

字段映射只能与 WS_FIELD_OPTIONS 值为 0 一起使用。


结构结构
{
    int 字段;
};

结构;
s.field = 1;


              <结构/>
WS_XML_ATTRIBUTE_FIELD_MAPPING
值：6
该字段对应于保留的 xml 属性（如 xml：lang）。

字段的 localName 用于标识 XML 属性名称。

除非指定了 WS_FIELD_OPTIONAL，否则属性必须显示在 XML 中。 如果指定了 WS_FIELD_OPTIONAL，则不需要在 XML 中显示该属性。 如果可选且不存在，则字段设置为 WS_DEFAULT_VALUE;如果未指定默认值，则为零。


结构结构
{
    WS_STRING字段;
};

结构;
s.field = ...;“us-en”;

xml：lang 的示例

              <结构 xml：lang='us-en“/>

s.field = ...;“true”

xml：space 的示例

              <结构 xml：space='true'>
WS_ELEMENT_CHOICE_FIELD_MAPPING
值：7
该字段对应于一组可能元素之间的选择。 每个元素映射到联合的一个字段。 联合的每个字段都有相应的枚举值，用于标识当前选择。


枚举不同值的选择
枚举选项
{
    ChoiceA = 10，
    ChoiceB = 20，
    None = 0，
};

包含值联合和枚举“selector”的结构
结构结构
{
    选择选项;
    联盟
    {
        int a;当选择为 ChoiceA 时有效
        WS_STRING b;当选择为 ChoiceB 时有效
    } 值;
};


此字段映射必须与 WS_UNION_TYPE一起使用。 元素选项的名称和命名空间在 WS_UNION_DESCRIPTION中指定。 字段的 localName 和 ns 应 NULL。

除非指定 WS_FIELD_OPTIONAL，否则其中一个元素必须出现在 XML 中。 如果指定了 WS_FIELD_OPTIONAL，则不需要在 XML 中显示任何元素。 如果可选且不存在任何元素，则字段的选择器值将设置为枚举的无值（如 WS_UNION_DESCRIPTION的 noneEnumValue 字段中指定的）。 由于 nonEnumValue 用作默认值，因此此映射值不支持指定 WS_DEFAULT_VALUE。


结构;
s.choice = ChoiceA;
s.value.a = 123;


              <结构>
    
              <choiceA>123</choiceA>

              </结构>

结构 S;
s.choice = ChoiceB;
s.value.b = ...;“你好”


              <结构>
    
              <choiceB>你好</choiceB>

              </结构>

结构 S;
s.choice = None;


              <结构>

              </结构>


该字段对应于一组可能元素之间的选择。 每个元素映射到联合的一个字段。 联合的每个字段都有相应的枚举值，用于标识当前选择。


枚举不同值的选择
枚举选项
{
    ChoiceA = 10，
    ChoiceB = 20，
    None = 0，
};

包含值联合的结构，以及枚举 &引用;selector"
结构结构
{
    选择选项;
    联盟
    {
        int a;当选择为 ChoiceA 时有效
        WS_STRING b;当选择为 ChoiceB 时有效
    } 值;
};


此字段映射必须与 WS_UNION_TYPE一起使用。 元素选项的名称和命名空间在 WS_UNION_DESCRIPTION中指定。 字段的 localName 和 ns 应 NULL。

除非指定 WS_FIELD_OPTIONAL，否则其中一个元素必须出现在 XML 中。 如果指定了 WS_FIELD_OPTIONAL，则不需要在 XML 中显示任何元素。 如果可选且不存在任何元素，则字段的选择器值将设置为枚举的无值（如 WS_UNION_DESCRIPTION的 noneEnumValue 字段中指定的）。 由于 nonEnumValue 用作默认值，因此此映射值不支持指定 WS_DEFAULT_VALUE。


结构;
s.choice = ChoiceA;
s.value.a = 123;


              <结构>
    
              <choiceA>123</choiceA>

              </结构>

结构 S;
s.choice = ChoiceB;
s.value.b = ...;&引用;你好&引用;


              <结构>
    
              <choiceB>你好</choiceB>

              </结构>

结构 S;
s.choice = None;


              <结构>

              </结构>


选择器值指示设置了哪个联合字段。 反序列化值时，其他字段将保持未初始化。 应用程序应始终咨询选择器值，以验证联合字段是否可访问。
WS_REPEATING_ELEMENT_CHOICE_FIELD_MAPPING
值：8
该字段对应于一组重复的元素选项。

每个项由具有选择器值的联合表示。 此映射必须与 WS_UNION_TYPE一起使用。

字段的 localName/ns 用作 XML 元素名称和命名空间，用于包装元素（作为重复元素的父元素）。 如果不需要包装元素，则两个 localName/ns 都应 NULL。

如果指定了包装元素，则在重复元素计数不是 0 时，包装元素必须出现在 XML 中。 不能为此字段映射指定 WS_DEFAULT_VALUE。

itemLocalName 和 itemNs 字段必须 NULL。 XML 元素名称和命名空间在 WS_UNION_DESCRIPTION中定义。


结构结构 2
{
    结构* 字段;有关结构定义，请参阅WS_UNION_DESCRIPTION
    ULONG fieldCount;
};

StructType 值[2];
values[0].choice = ChoiceA;
values[0].values.a = 123;
values[1].choice = ChoiceB;
values[1].values.b = ...;你好

结构 2 s2;
s2.field = 值;
s2.fieldCount = 2;

指定了包装元素

              <结构 2>
    
              <字段>
        
              <项>123</item>
        
              <项>你好</item>
    
              </field>

              </Struct2>

未指定包装元素

              <结构 2>
    
              <项>123</item>
    
              <项>你好</item>

              </Struct2>


可以通过指定属于 WS_FIELD_DESCRIPTION的非NULLWS_ITEM_RANGE 结构来约束反序列化数组中的元素数。
WS_ANY_ELEMENT_FIELD_MAPPING
值：9
待定
WS_REPEATING_ANY_ELEMENT_FIELD_MAPPING
值：10
该字段用于放弃或存储具有任何名称和命名空间的元素序列。

若要存储元素，应使用 WS_XML_BUFFER_TYPE。 这对应于 WS_XML_BUFFER的数组，如下所示：


结构结构
{
    // ...已知字段...
    WS_XML_BUFFER** 字段;
    ULONG fieldCount;
    // ...已知字段...
};

结构;
s.fields = ...;{ '<unknown1/>'， '<unknown2/>'; }
s.fieldCount = 2;


              <结构>
    ...已知字段...
    
              <未知1/>
    
              <未知2/>
    ...已知字段...

              </结构>


若要放弃元素，应使用 WS_VOID_TYPE。 在这种情况下，结构中不需要字段。 有关详细信息，请参阅 WS_VOID_TYPE。

反序列化期间允许的元素数可以通过指定属于 WS_FIELD_DESCRIPTION的非NULLWS_ITEM_RANGE 结构来约束。

此映射不支持指定 WS_DEFAULT_VALUE。
WS_ANY_CONTENT_FIELD_MAPPING
值：11
该字段用于放弃或存储元素末尾之前发生的任何剩余内容（任何文本或元素的混合体）。

若要存储元素，应使用 WS_XML_BUFFER_TYPE，如下所示：


结构结构
{
    // ...已知字段...
    WS_XML_BUFFER* 字段;
};

结构;
s.field = ...;“text1<unknown1/>text2<unknown2/>”


              <结构>
    ...已知字段...
    text1
    
              <未知1/>
    text2
    
              <未知2/>

              </结构>


若要放弃元素，应使用 WS_VOID_TYPE。 在这种情况下，结构中不需要字段。 有关详细信息，请参阅 WS_VOID_TYPE。

此映射不支持指定 WS_DEFAULT_VALUE。
WS_ANY_ATTRIBUTES_FIELD_MAPPING
值：12
该字段用于放弃或存储未使用其他 WS_FIELD_MAPPING 值映射的任何属性。

如果未指定此字段映射，则反序列化时，未映射的属性将导致错误。

WS_FIELD_DESCRIPTION 的名称字段必须 NULL。

WS_FIELD_DESCRIPTION 的 ns 字段限制允许的属性的命名空间，如下所示：


  • 如果 ns 字段 NULL，则没有任何限制。 这
    在这种情况下，不得设置 WS_FIELD_OTHER_NAMESPACE 字段选项。

  • 如果 ns 字段为非NULL，则为字段选项
    未为字段设置 WS_FIELD_OTHER_NAMESPACE，然后
    该特性必须具有与 ns 字段中指定的命名空间相同的命名空间。

  • 如果 ns 字段为非NULL，则为字段选项
    为字段设置 WS_FIELD_OTHER_NAMESPACE，然后为
    特性必须具有与指定的命名空间不同的命名空间
    在 ns 字段中。



若要存储属性，应使用 WS_ANY_ATTRIBUTES_TYPE。 这对应于 WS_ANY_ATTRIBUTES，如下所示：


结构结构
{
    // ...已知属性...
    WS_ANY_ATTRIBUTES字段;
    // ...其他内容...
};

结构;
s.field = ...;“unknown”/“http://example.com”/“value”


              <结构
    ...已知属性...
    xmlns：a='http://example.com'a：unknown='value'>

    ...其他内容...

              </结构>


若要放弃未映射的属性，应使用 WS_VOID_TYPE。 在这种情况下，结构中不需要字段。 有关详细信息，请参阅 WS_VOID_TYPE。

此映射不支持指定 WS_DEFAULT_VALUE。

言论

WS_FIELD_MAPPING 指示 XML 内容的不同部分如何映射到结构字段。 例如，WS_ELEMENT_FIELD_MAPPING 可用于映射子元素的值，WS_ATTRIBUTE_FIELD_MAPPING 可用于映射属性。 未显式映射的任何读取 XML 内容都将导致反序列化 XML 时返回 WS_E_INVALID_FORMAT（请参阅 Windows Web Services 返回值。）

WS_STRUCT_DESCRIPTION 内 WS_FIELD_DESCRIPTION 的顺序由 WS_FIELD_DESCRIPTION的 WS_FIELD_MAPPING 值决定。 有关订购的详细信息，请参阅 WS_STRUCT_DESCRIPTION。

要求

要求 价值
最低支持的客户端 Windows 7 [仅限桌面应用]
支持的最低服务器 Windows Server 2008 R2 [仅限桌面应用]
标头 webservices.h