Compartir a través de

enumeración WS_FIELD_MAPPING (webservices.h)

  • Artículo

Especifica cómo se representa un campo de una estructura en XML. Esto se usa dentro de un WS_FIELD_DESCRIPTION.

Sintaxis

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
Valor: 0
El campo corresponde al atributo de tipo XML (xsi:type). Solo se puede usar con WS_DESCRIPTION_TYPE. 


Base de estructura
{
    tipo WS_STRUCT_DESCRIPTION*;

    // ... campos base ...
};

Estructura derivada: Base
{
    // ... campos derivados ...
};

struct Struct
{
    Campo Base*;
};

Derivado;
derived.type = &DerivedStructDescription;
Estructura s;
s.field = &derivado;


              <Struct>
    
              <campo xsi:type='Derived'>
        // ... campos base ...
        // ... campos derivados ...
    
              </field>

              </Struct>


Esta asignación no admite la especificación de un WS_DEFAULT_VALUE.
WS_ATTRIBUTE_FIELD_MAPPING
Valor: 1
El campo corresponde a un único atributo.

El localName/ns del campo se usa como el nombre y el espacio de nombres del atributo XML.

A menos que se especifique, el atributo debe aparecer en el XML. Si se especifica WS_FIELD_OPTIONAL, no es necesario que el atributo aparezca en el XML. Si es opcional y no está presente, el campo se establece en el WS_DEFAULT_VALUE, o cero si no se especifica el valor predeterminado.


struct Struct
{
    campo int;
};

Estructura s;
s.field = 1;


              <campo de estructura='1'/>


Para descartar el atributo , se debe usar un WS_VOID_TYPE. En este caso, no se requiere un campo en la estructura. Consulte WS_VOID_TYPE para obtener más información.
WS_ELEMENT_FIELD_MAPPING
Valor: 2
El campo corresponde a un único elemento.

El localName/ns del campo se usa como nombre y espacio de nombres del elemento XML.

A menos que se especifique, el elemento debe aparecer en el XML. Si se especifica WS_FIELD_OPTIONAL, no es necesario que el elemento aparezca en el XML. Si es opcional y no está presente, el campo se establece en el WS_DEFAULT_VALUE, o cero si no se especifica el valor predeterminado.


struct Struct
{
    campo int;
};

Estructura s;
s.field = 1;


              <Struct>
    
              <campo>1</field>

              </Struct>


Para descartar el elemento , se debe usar un WS_VOID_TYPE. En este caso, no se requiere un campo en la estructura. Consulte WS_VOID_TYPE para obtener más información.
WS_REPEATING_ELEMENT_FIELD_MAPPING
Valor: 3
El campo corresponde a un conjunto repetido de elementos.

El localName/ns del campo se usa como nombre y espacio de nombres del elemento XML que se va a usar para el elemento contenedor (el elemento primario de los elementos repetidos). Si no se desea ningún elemento contenedor, tanto localName/ns deben ser NULL.

Si se ha especificado un elemento contenedor, el elemento contenedor debe aparecer en el XML si el recuento de elementos repetidos no es 0. Es posible que no se especifique un WS_DEFAULT_VALUE para esta asignación de campos.

Los itemLocalName y itemN se usan como el nombre y el espacio de nombres del elemento XML para el elemento repetido.


struct Struct
{
    campo int*;
    Campo ULONGCount;
};

int values[] = { 1, 2 };
Estructura s;
s.field = valores;
s.fieldCount = 2;

con el elemento contenedor especificado

              <Struct>
    
              <
              > de campo
        
              <elemento>1</item>
        
              <elemento>2</item>
    
              </field>

              </Struct>

sin elemento contenedor especificado

              <Struct>
    
              <elemento>1</item>
    
              <elemento>2</item>

              </Struct>


El número de elementos de la matriz deserializada se puede restringir especificando una estructura deWS_ITEM_RANGE NULL que no esque forma parte de la WS_FIELD_DESCRIPTION.
WS_TEXT_FIELD_MAPPING
Valor: 4
El campo corresponde a todo el contenido de caracteres del elemento. Cuando se usa esta asignación, no se permiten elementos secundarios.

Esta asignación se usa normalmente junto con WS_ATTRIBUTE_FIELD_MAPPING para definir una estructura que se asigna a un elemento que contiene algunos atributos y texto (pero no elementos secundarios).


struct Struct
{
    campo int;
};

Estructura s;
s.field = 1;


              <Struct>1</Struct>


Esta asignación no admite la especificación de un WS_DEFAULT_VALUE.
WS_NO_FIELD_MAPPING
Valor: 5
El campo no está serializado ni deserializado.

El campo se omite al serializar y se inicializa en el valor predeterminado al deserializar.

Si el campo se asigna a uno de los tipos existentes (por ejemplo, WS_INT32_TYPE), se puede especificar el tipo. Si el tipo del campo no es uno de los tipos existentes, se puede usar WS_VOID_TYPE para especificar un campo de un tipo arbitrario y un tamaño.

Se puede especificar un WS_DEFAULT_VALUE para proporcionar el valor para inicializar el campo a al deserializar el campo. Si no se especifica un valor predeterminado, el campo se inicializará en cero.

La asignación de campos solo se puede usar con WS_FIELD_OPTIONS valor de 0.


struct Struct
{
    campo int;
};

Estructura s;
s.field = 1;


              <Struct/>
WS_XML_ATTRIBUTE_FIELD_MAPPING
Valor: 6
El campo corresponde a un atributo xml reservado (por ejemplo, xml:lang).

LocalName del campo se usa para identificar el nombre del atributo XML.

A menos que se especifique WS_FIELD_OPTIONAL, el atributo debe aparecer en el XML. Si se especifica WS_FIELD_OPTIONAL, no es necesario que el atributo aparezca en el XML. Si es opcional y no está presente, el campo se establece en el WS_DEFAULT_VALUE, o cero si no se especifica el valor predeterminado.


struct Struct
{
    WS_STRING campo;
};

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

Ejemplo de xml:lang

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

s.field = ...; 'true'

Ejemplo de xml:space

              <Struct xml:space='true'>
WS_ELEMENT_CHOICE_FIELD_MAPPING
Valor: 7
El campo corresponde a una opción entre un conjunto de posibles elementos. Cada elemento se asigna a uno de los campos de una unión. Cada campo de la unión tiene un valor de enumeración correspondiente, que se usa para identificar la opción actual.


Enumeración de opciones de valores diferentes
enum Choice
{
    ChoiceA = 10,
    ChoiceB = 20,
    Ninguno = 0,
};

Estructura que contiene la unión de valores y enumeración 'selector'
struct Struct
{
    Elección;
    unión
    {
        int a; válido cuando choice es ChoiceA
        WS_STRING b; válido cuando la opción es ChoiceB
    } value;
};


Esta asignación de campos debe usarse con WS_UNION_TYPE. Los nombres y espacios de nombres de las opciones de elemento se especifican en el WS_UNION_DESCRIPTION. El valor localName y ns del campo deben ser NULL.

A menos que se especifique WS_FIELD_OPTIONAL, uno de los elementos debe aparecer en el XML. Si se especifica WS_FIELD_OPTIONAL, no se requiere ninguno de los elementos para que aparezcan en el XML. Si es opcional y ninguno de los elementos están presentes, el valor del selector del campo se establece en el valor none de la enumeración (como se especifica en el campo noneEnumValue del WS_UNION_DESCRIPTION). Debido al hecho de que nonEnumValue se usa como valor predeterminado, este valor de asignación no admite especificar un WS_DEFAULT_VALUE.


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


              <Struct>
    
              <choiceA>123</choiceA>

              </Struct>

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


              <Struct>
    
              <choiceB>hello</choiceB>

              </Struct>

Estructura S;
s.choice = None;


              <Struct>

              </Struct>


El campo corresponde a una opción entre un conjunto de posibles elementos. Cada elemento se asigna a uno de los campos de una unión. Cada campo de la unión tiene un valor de enumeración correspondiente, que se usa para identificar la opción actual.


Enumeración de opciones de valores diferentes
enum Choice
{
    ChoiceA = 10,
    ChoiceB = 20,
    Ninguno = 0,
};

Estructura que contiene la unión de valores y enumeración " selector"
struct Struct
{
    Elección;
    unión
    {
        int a; válido cuando choice es ChoiceA
        WS_STRING b; válido cuando la opción es ChoiceB
    } value;
};


Esta asignación de campos debe usarse con WS_UNION_TYPE. Los nombres y espacios de nombres de las opciones de elemento se especifican en el WS_UNION_DESCRIPTION. El valor localName y ns del campo deben ser NULL.

A menos que se especifique WS_FIELD_OPTIONAL, uno de los elementos debe aparecer en el XML. Si se especifica WS_FIELD_OPTIONAL, no se requiere ninguno de los elementos para que aparezcan en el XML. Si es opcional y ninguno de los elementos están presentes, el valor del selector del campo se establece en el valor none de la enumeración (como se especifica en el campo noneEnumValue del WS_UNION_DESCRIPTION). Debido al hecho de que nonEnumValue se usa como valor predeterminado, este valor de asignación no admite especificar un WS_DEFAULT_VALUE.


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


              <Struct>
    
              <choiceA>123</choiceA>

              </Struct>

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


              <Struct>
    
              <choiceB>hello</choiceB>

              </Struct>

Estructura S;
s.choice = None;


              <Struct>

              </Struct>


El valor del selector indica cuáles de los campos de la unión se establecen. Otros campos se dejan sin inicializar cuando el valor se deserializa. Una aplicación siempre debe consultar el valor del selector para comprobar que se puede acceder a un campo de la unión.
WS_REPEATING_ELEMENT_CHOICE_FIELD_MAPPING
Valor: 8
El campo corresponde a un conjunto repetido de opciones de elemento.

Cada elemento se representa mediante una unión con el valor del selector. Esta asignación debe usarse con WS_UNION_TYPE.

El localName/ns del campo se usa como nombre y espacio de nombres del elemento XML que se va a usar para el elemento contenedor (el elemento primario de los elementos repetidos). Si no se desea ningún elemento contenedor, tanto localName/ns deben ser NULL.

Si se ha especificado un elemento contenedor, el elemento contenedor debe aparecer en el XML si el recuento de elementos repetidos no es 0. Es posible que no se especifique un WS_DEFAULT_VALUE para esta asignación de campos.

Los campos itemLocalName y itemNs deben ser NULL. El nombre y el espacio de nombres del elemento XML se definen en el WS_UNION_DESCRIPTION.


struct Struct2
{
    Campo Struct*; consulte WS_UNION_DESCRIPTION para obtener la definición de Struct.
    Campo ULONGCount;
};

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

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

con el elemento contenedor especificado

              > Struct2 de <
    
              <
              > de campo
        
              <elemento>123</item>
        
              <elemento>hello</item>
    
              </field>

              </Struct2>

sin elemento contenedor especificado

              > Struct2 de <
    
              <elemento>123</item>
    
              <elemento>hello</item>

              </Struct2>


El número de elementos de la matriz deserializada se puede restringir especificando una estructura deWS_ITEM_RANGE NULL que no esque forma parte de la WS_FIELD_DESCRIPTION.
WS_ANY_ELEMENT_FIELD_MAPPING
Valor: 9
TBD
WS_REPEATING_ANY_ELEMENT_FIELD_MAPPING
Valor: 10
El campo se usa para descartar o almacenar una secuencia de elementos con cualquier nombre y espacio de nombres.

Para almacenar los elementos, se debe usar un WS_XML_BUFFER_TYPE. Esto corresponde a una matriz de WS_XML_BUFFERs, como se indica a continuación:


struct Struct
{
    // ... campos conocidos ...
    WS_XML_BUFFER** campos;
    Campo ULONGCount;
    // ... campos conocidos ...
};

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


              <Struct>
    ... campos conocidos ...
    
              <desconocido1/>
    
              <desconocido2/>
    ... campos conocidos ...

              </Struct>


Para descartar los elementos, se debe usar un WS_VOID_TYPE. En este caso, no se requiere un campo en la estructura. Consulte WS_VOID_TYPE para obtener más información.

El número de elementos permitidos durante la deserialización se puede restringir especificando una estructura deWS_ITEM_RANGE NULL que no esque forma parte de la WS_FIELD_DESCRIPTION.

Esta asignación no admite la especificación de un WS_DEFAULT_VALUE.
WS_ANY_CONTENT_FIELD_MAPPING
Valor: 11
El campo se usa para descartar o almacenar cualquier contenido restante (cualquier mezcla de texto o elementos) que se produzca antes del final de un elemento.

Para almacenar los elementos, se debe usar un WS_XML_BUFFER_TYPE, como se indica a continuación:


struct Struct
{
    // ... campos conocidos ...
    campo WS_XML_BUFFER*;
};

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


              <Struct>
    ... campos conocidos ...
    text1
    
              <desconocido1/>
    text2
    
              <desconocido2/>

              </Struct>


Para descartar los elementos, se debe usar un WS_VOID_TYPE. En este caso, no se requiere un campo en la estructura. Consulte WS_VOID_TYPE para obtener más información.

Esta asignación no admite la especificación de un WS_DEFAULT_VALUE.
WS_ANY_ATTRIBUTES_FIELD_MAPPING
Valor: 12
El campo se usa para descartar o almacenar los atributos que no se asignaron mediante otros valores de WS_FIELD_MAPPING.

Si no se especifica esta asignación de campos, los atributos sin asignar provocarán un error al deserializar.

El campo de nombre del WS_FIELD_DESCRIPTION debe ser NULL.

El campo ns del WS_FIELD_DESCRIPTION restringe el espacio de nombres de los atributos permitidos de la siguiente manera:


  • Si el campo ns es NULL, no hay ninguna restricción. El
    WS_FIELD_OTHER_NAMESPACE opción de campo no debe establecerse en este caso.

  • Si el campo ns no esNULLy la opción de campo
    WS_FIELD_OTHER_NAMESPACE no está establecido para el campo y, a continuación,
    el atributo debe tener el mismo espacio de nombres que se especificó en el campo ns.

  • Si el campo ns no esNULLy la opción de campo
    WS_FIELD_OTHER_NAMESPACE se establece para el campo y, a continuación, el
    el atributo debe tener un espacio de nombres diferente al especificado.
    en el campo ns.



Para almacenar los atributos, se debe usar WS_ANY_ATTRIBUTES_TYPE. Esto corresponde a WS_ANY_ATTRIBUTES de la siguiente manera:


struct Struct
{
    // ... atributos conocidos ...
    WS_ANY_ATTRIBUTES campo;
    // ... otro contenido...
};

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

Struct de <
    ... atributos conocidos ... 
    xmlns:a='http://example.com' a:unknown='value'>

    ... otro contenido...

              </Struct>


Para descartar los atributos no asignados, se debe usar un WS_VOID_TYPE. En este caso, no se requiere un campo en la estructura. Consulte WS_VOID_TYPE para obtener más información.

Esta asignación no admite la especificación de un WS_DEFAULT_VALUE.

Observaciones

El WS_FIELD_MAPPING indica cómo se asignan diferentes partes del contenido XML a los campos de una estructura. Por ejemplo, WS_ELEMENT_FIELD_MAPPING se puede usar para asignar el valor de un elemento secundario y WS_ATTRIBUTE_FIELD_MAPPING se puede usar para asignar un atributo. Cualquier contenido XML que se lea que no esté asignado explícitamente hará que se devuelva WS_E_INVALID_FORMAT cuando se deserialice el XML (vea valores devueltos de servicios web de Windows).

El orden del WS_FIELD_DESCRIPTION dentro de un WS_STRUCT_DESCRIPTION viene determinado por el valor WS_FIELD_MAPPING del WS_FIELD_DESCRIPTION. Consulte WS_STRUCT_DESCRIPTION para obtener más información sobre el pedido.

Requisitos

Requisito Valor
cliente mínimo admitido Windows 7 [solo aplicaciones de escritorio]
servidor mínimo admitido Windows Server 2008 R2 [solo aplicaciones de escritorio]
encabezado de webservices.h