Поделиться через

перечисление 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
{
    // ... производные поля ...
};

Структуру структуры
{
    Поле Base* ;
};

Производный производный;
derived.type = &DerivedStructDescription;
Структуры;
s.field = &производных;


              <структуры>
    
              <поле xsi:type='Derived'>
        // ... базовые поля ...
        // ... производные поля ...
    
              </field>

              </Struct>


Это сопоставление не поддерживает указание 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>

              </Struct>


Чтобы отменить элемент, необходимо использовать WS_VOID_TYPE. В этом случае поле не требуется в структуре. Дополнительные сведения см. в WS_VOID_TYPE.
WS_REPEATING_ELEMENT_FIELD_MAPPING
Значение: 3
Поле соответствует повторяющимся набору элементов.

LocalName/ns поля используются в качестве имени xml-элемента и пространства имен, используемых для элемента-оболочки (элемент, являющийся родительским элементом повторяющихся элементов). Если элемент оболочки не нжен, то оба localName/ns должны быть NULL.

Если был указан элемент-оболочка, элемент оболочки должен отображаться в XML, если число повторяющихся элементов не равно 0. Для сопоставления полей может быть не указана WS_DEFAULT_VALUE.

Элементы itemLocalName и itemNs используются в качестве имени и пространства имен XML-элемента для повторяющегося элемента.


Структуру структуры
{
    поле int* ;
    ULONG fieldCount;
};

int values[] = { 1, 2 };
Структуры;
s.field = значения;
s.fieldCount = 2;

с указанным элементом оболочки

              <структуры>
    
              <поле>
        
              <элемент>1</item>
        элемент <>2</item>
    
              </field>

              </Struct>

без указанного элемента оболочки

              <структуры>
    
              <элемент>1</item>
    элемент <>2</item>

              </Struct>


Количество элементов в десериализированном массиве может быть ограничено путем указания структуры, отличной отNULLWS_ITEM_RANGE, которая является частью WS_FIELD_DESCRIPTION.
WS_TEXT_FIELD_MAPPING
Значение: 4
Поле соответствует всему содержимому символа элемента. При использовании этого сопоставления дочерние элементы не допускаются.

Это сопоставление обычно используется в сочетании с WS_ATTRIBUTE_FIELD_MAPPING для определения структуры, которая сопоставляется с элементом, содержащим текст и атрибуты (но не дочерние элементы).


Структуру структуры
{
    поле int;
};

Структуры;
s.field = 1;


              <структуры>1</Struct>


Это сопоставление не поддерживает указание 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).

Имя локального поля используется для идентификации имени атрибута 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,
};

Структура, содержащая объединение значений и перечисление "селектор"
Структуру структуры
{
    Выбор выбора;
    союз
    {
        int a; допустимо, если выбор — ChoiceA
        WS_STRING b; допустимо, если выбор — ChoiceB
    } значение;
};


Это сопоставление полей должно использоваться с WS_UNION_TYPE. Имена и пространства имен выбора элементов указываются в WS_UNION_DESCRIPTION. Значение localName поля и ns должно быть null.

Если WS_FIELD_OPTIONAL не указано, один из элементов должен отображаться в XML. Если указан WS_FIELD_OPTIONAL, ни один из элементов не должен отображаться в XML. Если необязательный и ни один из элементов отсутствует, значение селектора поля равно ни одному значению перечисления (как указано в поле noneEnumValue WS_UNION_DESCRIPTION). Из-за того, что nonEnumValue используется в качестве значения по умолчанию, это значение сопоставления не поддерживает указание WS_DEFAULT_VALUE.


Структуры;
s.choice = ChoiceA;
s.value.a = 123;


              <структуры>
    
              <выборA>123</choiceA>

              </Struct>

Структуру S;
s.choice = ChoiceB;
s.value.b = ...; "hello"


              <структуры>
    
              <
              >hello</choiceB>

              </Struct>

Структуру S;
s.choice = None;


              <структуры>

              </Struct>


Поле соответствует выбору между набором возможных элементов. Каждый элемент сопоставляется с одним из полей объединения. Каждое поле объединения имеет соответствующее значение перечисления, которое используется для определения текущего выбора.


Перечисление вариантов различных значений
Выбор перечисления
{
    ChoiceA = 10,
    ChoiceB = 20,
    None = 0,
};

Структуру, содержащую объединение значений, и перечисление &кво; селектор&кво;
Структуру структуры
{
    Выбор выбора;
    союз
    {
        int a; допустимо, если выбор — ChoiceA
        WS_STRING b; допустимо, если выбор — ChoiceB
    } значение;
};


Это сопоставление полей должно использоваться с WS_UNION_TYPE. Имена и пространства имен выбора элементов указываются в WS_UNION_DESCRIPTION. Значение localName поля и ns должно быть null.

Если WS_FIELD_OPTIONAL не указано, один из элементов должен отображаться в XML. Если указан WS_FIELD_OPTIONAL, ни один из элементов не должен отображаться в XML. Если необязательный и ни один из элементов отсутствует, значение селектора поля равно ни одному значению перечисления (как указано в поле noneEnumValue WS_UNION_DESCRIPTION). Из-за того, что nonEnumValue используется в качестве значения по умолчанию, это значение сопоставления не поддерживает указание WS_DEFAULT_VALUE.


Структуры;
s.choice = ChoiceA;
s.value.a = 123;


              <структуры>
    
              <выборA>123</choiceA>

              </Struct>

Структуру S;
s.choice = ChoiceB;
s.value.b = ...; &кво; hello"


              <структуры>
    
              <
              >hello</choiceB>

              </Struct>

Структуру S;
s.choice = None;


              <структуры>

              </Struct>


Значение селектора указывает, какие поля объединения заданы. Другие поля остаются неинициализированными при десериализации значения. Приложение всегда должно обращаться к значению селектора, чтобы убедиться, что поле объединения доступно.
WS_REPEATING_ELEMENT_CHOICE_FIELD_MAPPING
Значение: 8
Поле соответствует повторяющимся набору вариантов элементов.

Каждый элемент представлен объединением со значением селектора. Это сопоставление должно использоваться с WS_UNION_TYPE.

LocalName/ns поля используются в качестве имени xml-элемента и пространства имен, используемых для элемента-оболочки (элемент, являющийся родительским элементом повторяющихся элементов). Если элемент оболочки не нжен, то оба localName/ns должны быть NULL.

Если был указан элемент-оболочка, элемент оболочки должен отображаться в XML, если число повторяющихся элементов не равно 0. Для сопоставления полей может быть не указана WS_DEFAULT_VALUE.

Поля itemLocalName и itemNs должны быть NULL. Имя и пространство имен XML-элемента определяются в WS_UNION_DESCRIPTION.


Структуры 2
{
    Поле структуры* ; см. WS_UNION_DESCRIPTION определения структуры
    ULONG fieldCount;
};

Значения StructType[2];
значения[0].choice = ChoiceA;
значения[0].values.a = 123;
значения[1].choice = ChoiceB;
значения[1].values.b = ...; Привет

Struct2 s2;
s2.field = значения;
s2.fieldCount = 2;

с указанным элементом оболочки

              <Struct2>
    
              <поле>
        
              <элемент>123</item>
        
              <элемент>hello</item>
    
              </field>

              </Struct2>

без указанного элемента оболочки

              <Struct2>
    
              <элемент>123</item>
    
              <элемент>hello</item>

              </Struct2>


Количество элементов в десериализированном массиве может быть ограничено путем указания структуры, отличной отNULLWS_ITEM_RANGE, которая является частью WS_FIELD_DESCRIPTION.
WS_ANY_ELEMENT_FIELD_MAPPING
Значение: 9
ТБD
WS_REPEATING_ANY_ELEMENT_FIELD_MAPPING
Значение: 10
Поле используется для отмены или хранения последовательности элементов с любым пространством имен и имен.

Для хранения элементов следует использовать WS_XML_BUFFER_TYPE. Это соответствует массиву WS_XML_BUFFERs, как показано ниже.


Структуру структуры
{
    // ... известные поля ...
    поля WS_XML_BUFFER** ;
    ULONG fieldCount;
    // ... известные поля ...
};

Структуры;
s.fields = ...; { '<unknown1/>', '<unknown2/>'; }
s.fieldCount = 2;


              <структуры>
    ... известные поля ...
    
              <неизвестно1/>
    
              <неизвестно2/>
    ... известные поля ...

              </Struct>


Чтобы отменить элементы, следует использовать WS_VOID_TYPE. В этом случае поле не требуется в структуре. Дополнительные сведения см. в WS_VOID_TYPE.

Количество элементов, разрешенных во время десериализации, может быть ограничено путем указания структуры, отличной отNULLWS_ITEM_RANGE, которая является частью WS_FIELD_DESCRIPTION.

Это сопоставление не поддерживает указание 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/>

              </Struct>


Чтобы отменить элементы, следует использовать WS_VOID_TYPE. В этом случае поле не требуется в структуре. Дополнительные сведения см. в WS_VOID_TYPE.

Это сопоставление не поддерживает указание WS_DEFAULT_VALUE.
WS_ANY_ATTRIBUTES_FIELD_MAPPING
Значение: 12
Поле используется для отмены или хранения атрибутов, которые не были сопоставлены с другими значениями WS_FIELD_MAPPING.

Если это сопоставление полей не указано, при десериализации необнаруженные атрибуты вызывают ошибку.

Поле имени WS_FIELD_DESCRIPTION должно быть NULL.

Поле ns WS_FIELD_DESCRIPTION ограничивает пространство имен атрибутов, разрешенное следующим образом:


  • Если поле 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 = ...; "неизвестно"/"http://example.com"/"value"

Структуру <
    ... известные атрибуты ... 
    xmlns:a='http://example.com' a:unknown='value'>

    ... другое содержимое ...

              </Struct>


Чтобы отменить несопоставленные атрибуты, следует использовать WS_VOID_TYPE. В этом случае поле не требуется в структуре. Дополнительные сведения см. в WS_VOID_TYPE.

Это сопоставление не поддерживает указание WS_DEFAULT_VALUE.

Замечания

WS_FIELD_MAPPING указывает, как различные части XML-содержимого сопоставляют поля структуры. Например, WS_ELEMENT_FIELD_MAPPING можно использовать для сопоставления значения дочернего элемента, а WS_ATTRIBUTE_FIELD_MAPPING можно использовать для сопоставления атрибута. Любое содержимое XML, которое не сопоставляется явно, приведет к возврату WS_E_INVALID_FORMAT при десериализации XML (см. возвращаемые значения веб-служб Windows.)

Порядок WS_FIELD_DESCRIPTION в WS_STRUCT_DESCRIPTION определяется значением WS_FIELD_MAPPINGWS_FIELD_DESCRIPTION. Дополнительные сведения о заказе см. в WS_STRUCT_DESCRIPTION.

Требования

Требование Ценность
минимальные поддерживаемые клиентские Windows 7 [только классические приложения]
минимальный поддерживаемый сервер Windows Server 2008 R2 [только классические приложения]
заголовка webservices.h