WS_FIELD_MAPPING enumeração (webservices.h)

  • Artigo

Especifica como um campo de uma estrutura é representado em XML. Isso é usado em um WS_FIELD_DESCRIPTION.

Sintaxe

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
O campo corresponde ao atributo de tipo XML (xsi:type). Isso só pode ser usado com WS_DESCRIPTION_TYPE. 


struct Base
{
    tipo WS_STRUCT_DESCRIPTION*;

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

struct Derivado: Base
{
    // ... campos derivados...
};

struct Struct
{
    Campo Base*;
};

Derivada;
derived.type = &DerivedStructDescription;
Struct s;
s.field = &derivado;


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

              </Struct>


Esse mapeamento não dá suporte à especificação de um WS_DEFAULT_VALUE.
WS_ATTRIBUTE_FIELD_MAPPING
Valor: 1
O campo corresponde a um único atributo.

O localName/ns do campo é usado como o nome do atributo XML e o namespace.

A menos que especificado, o atributo deve aparecer no XML. Se WS_FIELD_OPTIONAL for especificado, o atributo não será necessário para aparecer no XML. Se opcional e não estiver presente, o campo será definido como o WS_DEFAULT_VALUEou zero se o valor padrão não for especificado.


struct Struct
{
    campo int;
};

Struct s;
s.field = 1;


              <campo Struct='1'/>


Para descartar o atributo, um WS_VOID_TYPE deve ser usado. Nesse caso, um campo não é necessário na estrutura. Consulte WS_VOID_TYPE para obter mais informações.
WS_ELEMENT_FIELD_MAPPING
Valor: 2
O campo corresponde a um único elemento.

O localName/ns do campo é usado como o nome e o namespace do elemento XML.

A menos que especificado, o elemento deve aparecer no XML. Se WS_FIELD_OPTIONAL for especificado, o elemento não será necessário para aparecer no XML. Se opcional e não estiver presente, o campo será definido como o WS_DEFAULT_VALUEou zero se o valor padrão não for especificado.


struct Struct
{
    campo int;
};

Struct s;
s.field = 1;


              <Struct>
    
              <campo>1</field>

              </Struct>


Para descartar o elemento, um WS_VOID_TYPE deve ser usado. Nesse caso, um campo não é necessário na estrutura. Consulte WS_VOID_TYPE para obter mais informações.
WS_REPEATING_ELEMENT_FIELD_MAPPING
Valor: 3
O campo corresponde a um conjunto repetido de elementos.

O localName/ns do campo é usado como o nome do elemento XML e o namespace a ser usado para o elemento wrapper (o elemento que é o pai dos elementos recorrentes). Se nenhum elemento wrapper for desejado, o localName/ns deverá ser NULL.

Se um elemento wrapper tiver sido especificado, o elemento wrapper deverá aparecer no XML se a contagem de elementos recorrentes não for 0. Um WS_DEFAULT_VALUE pode não ser especificado para este mapeamento de campo.

O itemLocalName e os itemNs são usados como o nome do elemento XML e o namespace para o elemento recorrente.


struct Struct
{
    campo int*;
    ULONG fieldCount;
};

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

com o elemento wrapper especificado

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

              </Struct>

sem nenhum elemento wrapper especificado

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

              </Struct>


O número de elementos na matriz desserializada pode ser restringido especificando uma estrutura deWS_ITEM_RANGE NULL nãoque faz parte do WS_FIELD_DESCRIPTION.
WS_TEXT_FIELD_MAPPING
Valor: 4
O campo corresponde a todo o conteúdo do caractere do elemento. Quando esse mapeamento é usado, elementos filho não são permitidos.

Esse mapeamento é comumente usado em conjunto com WS_ATTRIBUTE_FIELD_MAPPING para definir uma estrutura que é mapeada para um elemento que contém alguns atributos e texto (mas nenhum elemento filho).


struct Struct
{
    campo int;
};

Struct s;
s.field = 1;


              <Struct>1</Struct>


Esse mapeamento não dá suporte à especificação de um WS_DEFAULT_VALUE.
WS_NO_FIELD_MAPPING
Valor: 5
O campo não é serializado nem desserializado.

O campo é ignorado ao serializar e é inicializado para o valor padrão ao desserializar.

Se o campo for mapeado para um dos tipos existentes (por exemplo, WS_INT32_TYPE), o tipo poderá ser especificado. Se o tipo do campo não for um dos tipos existentes, WS_VOID_TYPE poderá ser usado para especificar um campo de um tipo e tamanho arbitrários.

Um WS_DEFAULT_VALUE pode ser especificado para fornecer o valor para inicializar o campo ao desserializar o campo. Se um valor padrão não for especificado, o campo será inicializado como zero.

O mapeamento de campo só pode ser usado com WS_FIELD_OPTIONS valor de 0.


struct Struct
{
    campo int;
};

Struct s;
s.field = 1;

Struct/><
WS_XML_ATTRIBUTE_FIELD_MAPPING
Valor: 6
O campo corresponde a um atributo xml reservado (como xml:lang).

O localName do campo é usado para identificar o nome do atributo XML.

A menos que WS_FIELD_OPTIONAL seja especificado, o atributo deve aparecer no XML. Se WS_FIELD_OPTIONAL for especificado, o atributo não será necessário para aparecer no XML. Se opcional e não estiver presente, o campo será definido como o WS_DEFAULT_VALUEou zero se o valor padrão não for especificado.


struct Struct
{
    WS_STRING campo;
};

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

Exemplo de xml:lang

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

s.field = ...; 'true'

Exemplo de xml:space

              <Struct xml:space='true'>
WS_ELEMENT_CHOICE_FIELD_MAPPING
Valor: 7
O campo corresponde a uma escolha entre um conjunto de elementos possíveis. Cada elemento é mapeado para um dos campos de uma união. Cada campo da união tem um valor de enumeração correspondente, que é usado para identificar a escolha atual.


Enumeração de opções de valores diferentes
Opção de enumeração
{
    ChoiceA = 10,
    ChoiceB = 20,
    None = 0,
};

Struct que contém a união de valores e enumeração 'seletor'
struct Struct
{
    Opção de escolha;
    união
    {
        int a; válido quando a opção é ChoiceA
        WS_STRING b; válido quando a opção é ChoiceB
    } valor;
};


Esse mapeamento de campo deve ser usado com WS_UNION_TYPE. Os nomes e namespaces das opções de elemento são especificados no WS_UNION_DESCRIPTION. O localName e ns do campo devem ser NULL.

A menos que WS_FIELD_OPTIONAL seja especificado, um dos elementos deve aparecer no XML. Se WS_FIELD_OPTIONAL for especificado, nenhum dos elementos será necessário para aparecer no XML. Se forem opcionais e nenhum dos elementos estiverem presentes, o valor do seletor do campo será definido como o valor nenhum da enumeração (conforme especificado no campo noneEnumValue do WS_UNION_DESCRIPTION). Devido ao fato de que nonEnumValue é usado como o valor padrão, esse valor de mapeamento não dá suporte à especificação de um WS_DEFAULT_VALUE.


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


              <Struct>
    
              <choiceA>123</choiceA>

              </Struct>

Struct S;
s.choice = ChoiceB;
s.value.b = ...; 'olá'


              <Struct>
    
              <choiceB>hello</choiceB>

              </Struct>

Struct S;
s.choice = None;


              <Struct>

              </Struct>


O campo corresponde a uma escolha entre um conjunto de elementos possíveis. Cada elemento é mapeado para um dos campos de uma união. Cada campo da união tem um valor de enumeração correspondente, que é usado para identificar a escolha atual.


Enumeração de opções de valores diferentes
Opção de enumeração
{
    ChoiceA = 10,
    ChoiceB = 20,
    None = 0,
};

Struct contendo união de valores e enumeração &aspas; seletor&aspas;
struct Struct
{
    Opção de escolha;
    união
    {
        int a; válido quando a opção é ChoiceA
        WS_STRING b; válido quando a opção é ChoiceB
    } valor;
};


Esse mapeamento de campo deve ser usado com WS_UNION_TYPE. Os nomes e namespaces das opções de elemento são especificados no WS_UNION_DESCRIPTION. O localName e ns do campo devem ser NULL.

A menos que WS_FIELD_OPTIONAL seja especificado, um dos elementos deve aparecer no XML. Se WS_FIELD_OPTIONAL for especificado, nenhum dos elementos será necessário para aparecer no XML. Se forem opcionais e nenhum dos elementos estiverem presentes, o valor do seletor do campo será definido como o valor nenhum da enumeração (conforme especificado no campo noneEnumValue do WS_UNION_DESCRIPTION). Devido ao fato de que nonEnumValue é usado como o valor padrão, esse valor de mapeamento não dá suporte à especificação de um WS_DEFAULT_VALUE.


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


              <Struct>
    
              <choiceA>123</choiceA>

              </Struct>

Struct S;
s.choice = ChoiceB;
s.value.b = ...; &aspas; olá&aspas;


              <Struct>
    
              <choiceB>hello</choiceB>

              </Struct>

Struct S;
s.choice = None;


              <Struct>

              </Struct>


O valor do seletor indica quais dos campos da união estão definidos. Outros campos são deixados não inicializados quando o valor é desserializado. Um aplicativo sempre deve consultar o valor do seletor para verificar se um campo da união está acessível.
WS_REPEATING_ELEMENT_CHOICE_FIELD_MAPPING
Valor: 8
O campo corresponde a um conjunto repetido de opções de elemento.

Cada item é representado por uma união com o valor do seletor. Esse mapeamento deve ser usado com WS_UNION_TYPE.

O localName/ns do campo é usado como o nome do elemento XML e o namespace a ser usado para o elemento wrapper (o elemento que é o pai dos elementos recorrentes). Se nenhum elemento wrapper for desejado, o localName/ns deverá ser NULL.

Se um elemento wrapper tiver sido especificado, o elemento wrapper deverá aparecer no XML se a contagem de elementos recorrentes não for 0. Um WS_DEFAULT_VALUE pode não ser especificado para este mapeamento de campo.

Os campos itemLocalName e itemNs devem ser NULL. O nome e o namespace do elemento XML são definidos no WS_UNION_DESCRIPTION.


struct Struct2
{
    Campo Struct*; consulte WS_UNION_DESCRIPTION para definição de Struct
    ULONG fieldCount;
};

Valores de StructType[2];
values[0].choice = ChoiceA;
values[0].values.a = 123;
values[1].choice = ChoiceB;
values[1].values.b = ...; Olá

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

com o elemento wrapper especificado

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

              </Struct2>

sem nenhum elemento wrapper especificado

              <Struct2>
    
              <item>123</item>
    
              <item>hello</item>

              </Struct2>


O número de elementos na matriz desserializada pode ser restringido especificando uma estrutura deWS_ITEM_RANGE NULL nãoque faz parte do WS_FIELD_DESCRIPTION.
WS_ANY_ELEMENT_FIELD_MAPPING
Valor: 9
TBD
WS_REPEATING_ANY_ELEMENT_FIELD_MAPPING
Valor: 10
O campo é usado para descartar ou armazenar uma sequência de elementos com qualquer nome e namespace.

Para armazenar os elementos, um WS_XML_BUFFER_TYPE deve ser usado. Isso corresponde a uma matriz de WS_XML_BUFFERs, da seguinte maneira:


struct Struct
{
    // ... campos conhecidos...
    campos WS_XML_BUFFER**;
    ULONG fieldCount;
    // ... campos conhecidos...
};

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


              <Struct>
    ... campos conhecidos...
    
              <desconhecido1/>
    
              <desconhecido2/>
    ... campos conhecidos...

              </Struct>


Para descartar os elementos, um WS_VOID_TYPE deve ser usado. Nesse caso, um campo não é necessário na estrutura. Consulte WS_VOID_TYPE para obter mais informações.

O número de elementos permitidos durante a desserialização pode ser restringido especificando uma estrutura deWS_ITEM_RANGE NULL nãoque faz parte do WS_FIELD_DESCRIPTION.

Esse mapeamento não dá suporte à especificação de um WS_DEFAULT_VALUE.
WS_ANY_CONTENT_FIELD_MAPPING
Valor: 11
O campo é usado para descartar ou armazenar qualquer conteúdo restante (qualquer mistura de texto ou elementos) que ocorra antes do final de um elemento.

Para armazenar os elementos, um WS_XML_BUFFER_TYPE deve ser usado, da seguinte maneira:


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

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


              <Struct>
    ... campos conhecidos...
    text1
    
              <desconhecido1/>
    text2
    
              <desconhecido2/>

              </Struct>


Para descartar os elementos, um WS_VOID_TYPE deve ser usado. Nesse caso, um campo não é necessário na estrutura. Consulte WS_VOID_TYPE para obter mais informações.

Esse mapeamento não dá suporte à especificação de um WS_DEFAULT_VALUE.
WS_ANY_ATTRIBUTES_FIELD_MAPPING
Valor: 12
O campo é usado para descartar ou armazenar quaisquer atributos que não foram mapeados usando outros valores WS_FIELD_MAPPING.

Se esse mapeamento de campo não for especificado, os atributos não mapeados causarão um erro ao desserializar.

O campo de nome do WS_FIELD_DESCRIPTION deve ser NULL.

O campo ns do WS_FIELD_DESCRIPTION restringe o namespace dos atributos permitidos da seguinte maneira:


  • Se o campo ns for NULL, não haverá restrição. O
    WS_FIELD_OTHER_NAMESPACE opção de campo não deve ser definida nesse caso.

  • Se o campo ns não forNULL e a opção de campo
    WS_FIELD_OTHER_NAMESPACE não está definido para o campo, então
    o atributo deve ter o mesmo namespace especificado no campo ns.

  • Se o campo ns não forNULL e a opção de campo
    WS_FIELD_OTHER_NAMESPACE é definido para o campo, em seguida, o
    o atributo deve ter um namespace diferente do especificado
    no campo ns.



Para armazenar os atributos, WS_ANY_ATTRIBUTES_TYPE deve ser usado. Isso corresponde a WS_ANY_ATTRIBUTES da seguinte maneira:


struct Struct
{
    // ... atributos conhecidos...
    WS_ANY_ATTRIBUTES campo;
    // ... outro conteúdo...
};

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

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

    ... outro conteúdo...

              </Struct>


Para descartar os atributos não mapeados, um WS_VOID_TYPE deve ser usado. Nesse caso, um campo não é necessário na estrutura. Consulte WS_VOID_TYPE para obter mais informações.

Esse mapeamento não dá suporte à especificação de um WS_DEFAULT_VALUE.

Observações

O WS_FIELD_MAPPING indica como diferentes partes do conteúdo XML são mapeadas para os campos de uma estrutura. Por exemplo, WS_ELEMENT_FIELD_MAPPING pode ser usado para mapear o valor de um elemento filho e WS_ATTRIBUTE_FIELD_MAPPING pode ser usado para mapear um atributo. Qualquer conteúdo XML lido que não esteja explicitamente mapeado fará com que WS_E_INVALID_FORMAT sejam retornados quando o XML for desserializado (consulte Os Serviços Web do Windows retornam valores.)

A ordem do WS_FIELD_DESCRIPTION em um WS_STRUCT_DESCRIPTION é determinada pelo valor WS_FIELD_MAPPING do WS_FIELD_DESCRIPTION. Consulte WS_STRUCT_DESCRIPTION para obter mais informações sobre a ordenação.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows 7 [somente aplicativos da área de trabalho]
servidor com suporte mínimo Windows Server 2008 R2 [somente aplicativos da área de trabalho]
cabeçalho webservices.h