Condividi tramite

enumerazione WS_FIELD_MAPPING (webservices.h)

  • Articolo

Specifica la modalità di rappresentazione di un campo di una struttura in XML. Viene usato all'interno di un WS_FIELD_DESCRIPTION.

Sintassi

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;

Costanti

 
WS_TYPE_ATTRIBUTE_FIELD_MAPPING
Valore: 0
Il campo corrisponde all'attributo di tipo XML (xsi:type). Questa operazione può essere usata solo con WS_DESCRIPTION_TYPE. 


Base struct
{
    WS_STRUCT_DESCRIPTION* tipo;

    // ... campi di base ...
};

struct derivato: base
{
    // ... campi derivati ...
};

Struct struct
{
    Campo base*;
};

Derivato;
derived.type = &DerivedStructDescription;
Struct s;
s.field = &derivata;


              <Struct>
    
              <campo xsi:type='Derivato'>
        // ... campi di base ...
        // ... campi derivati ...
    
              </field>

              </Struct>


Questo mapping non supporta la specifica di un WS_DEFAULT_VALUE.
WS_ATTRIBUTE_FIELD_MAPPING
Valore: 1
Il campo corrisponde a un singolo attributo.

I valori localName/ns del campo vengono usati come nome e spazio dei nomi dell'attributo XML.

A meno che non sia specificato, l'attributo deve essere visualizzato nel codice XML. Se si specifica WS_FIELD_OPTIONAL, l'attributo non deve essere visualizzato nel codice XML. Se facoltativo e non è presente, il campo viene impostato sul WS_DEFAULT_VALUEoppure zero se il valore predefinito non è specificato.


Struct struct
{
    campo int;
};

Struct s;
s.field = 1;


              <Struct field='1'/>


Per eliminare l'attributo, è necessario usare un WS_VOID_TYPE. In questo caso, un campo non è obbligatorio nella struttura. Per altre informazioni, vedere WS_VOID_TYPE.
WS_ELEMENT_FIELD_MAPPING
Valore: 2
Il campo corrisponde a un singolo elemento.

I valori localName/ns del campo vengono usati come nome e spazio dei nomi dell'elemento XML.

A meno che non sia specificato, l'elemento deve essere visualizzato nel codice XML. Se si specifica WS_FIELD_OPTIONAL, l'elemento non deve essere visualizzato nel codice XML. Se facoltativo e non è presente, il campo viene impostato sul WS_DEFAULT_VALUEoppure zero se il valore predefinito non è specificato.


Struct struct
{
    campo int;
};

Struct s;
s.field = 1;


              <Struct>
    
              <campo>1</field>

              </Struct>


Per eliminare l'elemento, è necessario usare un WS_VOID_TYPE. In questo caso, un campo non è obbligatorio nella struttura. Per altre informazioni, vedere WS_VOID_TYPE.
WS_REPEATING_ELEMENT_FIELD_MAPPING
Valore: 3
Il campo corrisponde a un set ripetuto di elementi.

I valori localName/ns del campo vengono usati come nome dell'elemento XML e spazio dei nomi da utilizzare per l'elemento wrapper (l'elemento padre degli elementi ripetuti). Se non si desidera alcun elemento wrapper, entrambi localName/ns devono essere NULL.

Se è stato specificato un elemento wrapper, l'elemento wrapper deve essere visualizzato nel codice XML se il numero di elementi ripetuti non è 0. Non è possibile specificare un WS_DEFAULT_VALUE per questo mapping dei campi.

Gli itemLocalName e itemN vengono utilizzati come nome e spazio dei nomi dell'elemento XML per l'elemento ripetuto.


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

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

con l'elemento wrapper specificato

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

              </Struct>

senza alcun elemento wrapper specificato

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

              </Struct>


Il numero di elementi nella matrice deserializzata può essere vincolato specificando una strutturaWS_ITEM_RANGE null nonche fa parte del WS_FIELD_DESCRIPTION.
WS_TEXT_FIELD_MAPPING
Valore: 4
Il campo corrisponde all'intero contenuto di caratteri dell'elemento. Quando viene usato questo mapping, gli elementi figlio non sono consentiti.

Questo mapping viene comunemente usato in combinazione con WS_ATTRIBUTE_FIELD_MAPPING per definire una struttura che esegue il mapping a un elemento contenente alcuni attributi e testo (ma senza elementi figlio).


Struct struct
{
    campo int;
};

Struct s;
s.field = 1;


              <Struct>1</Struct>


Questo mapping non supporta la specifica di un WS_DEFAULT_VALUE.
WS_NO_FIELD_MAPPING
Valore: 5
Il campo non è serializzato né deserializzato.

Il campo viene ignorato durante la serializzazione e viene inizializzato sul valore predefinito durante la deserializzazione.

Se il campo esegue il mapping a uno dei tipi esistenti , ad esempio WS_INT32_TYPE, è possibile specificare il tipo. Se il tipo del campo non è uno dei tipi esistenti, è possibile utilizzare WS_VOID_TYPE per specificare un campo di un tipo e una dimensione arbitrari.

È possibile specificare un WS_DEFAULT_VALUE per specificare il valore da inizializzare il campo a durante la deserializzazione del campo. Se non viene specificato un valore predefinito, il campo verrà inizializzato su zero.

Il mapping dei campi può essere usato solo con WS_FIELD_OPTIONS valore 0.


Struct struct
{
    campo int;
};

Struct s;
s.field = 1;


              <Struct/>
WS_XML_ATTRIBUTE_FIELD_MAPPING
Valore: 6
Il campo corrisponde a un attributo xml riservato ,ad esempio xml:lang.

Il valore localName del campo viene usato per identificare il nome dell'attributo XML.

A meno che non venga specificato WS_FIELD_OPTIONAL, l'attributo deve essere visualizzato nel codice XML. Se si specifica WS_FIELD_OPTIONAL, l'attributo non deve essere visualizzato nel codice XML. Se facoltativo e non è presente, il campo viene impostato sul WS_DEFAULT_VALUEoppure zero se il valore predefinito non è specificato.


Struct struct
{
    WS_STRING campo;
};

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

Esempio di xml:lang

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

s.field = ...; 'true'

Esempio di xml:space

              <Struct xml:space='true'>
WS_ELEMENT_CHOICE_FIELD_MAPPING
Valore: 7
Il campo corrisponde a una scelta tra un set di elementi possibili. Ogni elemento esegue il mapping a uno dei campi di un'unione. Ogni campo dell'unione ha un valore di enumerazione corrispondente, usato per identificare la scelta corrente.


Enumerazione delle scelte di valori diversi
enum Choice
{
    ChoiceA = 10,
    ChoiceB = 20,
    Nessuno = 0,
};

Struct contenente l'unione di valori ed enumerazione 'selector'
Struct struct
{
    Scelta;
    unione
    {
        int a; valido quando la scelta è ChoiceA
        WS_STRING b; valido quando la scelta è ChoiceB
    } value;
};


Questo mapping dei campi deve essere usato con WS_UNION_TYPE. I nomi e gli spazi dei nomi delle scelte degli elementi vengono specificati nella WS_UNION_DESCRIPTION. Il valore localName e ns del campo devono essere NULL.

A meno che non venga specificato WS_FIELD_OPTIONAL, uno degli elementi deve essere visualizzato nel codice XML. Se viene specificato WS_FIELD_OPTIONAL, non è necessario che nessuno degli elementi venga visualizzato nel codice XML. Se sono presenti elementi facoltativi e nessuno degli elementi, il valore del selettore del campo viene impostato sul valore none dell'enumerazione (come specificato nel campo noneEnumValue del WS_UNION_DESCRIPTION). A causa del fatto che il valore nonEnumValue viene usato come valore predefinito, questo valore di mapping non supporta la specifica di un WS_DEFAULT_VALUE.


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


              <Struct>
    
              <sceltaA>123</choiceA>

              </Struct>

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


              <Struct>
    
              <sceltaB>hello</choiceB>

              </Struct>

Struct S;
s.choice = Nessuno;


              <Struct>

              </Struct>


Il campo corrisponde a una scelta tra un set di elementi possibili. Ogni elemento esegue il mapping a uno dei campi di un'unione. Ogni campo dell'unione ha un valore di enumerazione corrispondente, usato per identificare la scelta corrente.


Enumerazione delle scelte di valori diversi
enum Choice
{
    ChoiceA = 10,
    ChoiceB = 20,
    Nessuno = 0,
};

Struct contenente l'unione di valori ed enumerazione &virgolette; selettore&virgolette;
Struct struct
{
    Scelta;
    unione
    {
        int a; valido quando la scelta è ChoiceA
        WS_STRING b; valido quando la scelta è ChoiceB
    } value;
};


Questo mapping dei campi deve essere usato con WS_UNION_TYPE. I nomi e gli spazi dei nomi delle scelte degli elementi vengono specificati nella WS_UNION_DESCRIPTION. Il valore localName e ns del campo devono essere NULL.

A meno che non venga specificato WS_FIELD_OPTIONAL, uno degli elementi deve essere visualizzato nel codice XML. Se viene specificato WS_FIELD_OPTIONAL, non è necessario che nessuno degli elementi venga visualizzato nel codice XML. Se sono presenti elementi facoltativi e nessuno degli elementi, il valore del selettore del campo viene impostato sul valore none dell'enumerazione (come specificato nel campo noneEnumValue del WS_UNION_DESCRIPTION). A causa del fatto che il valore nonEnumValue viene usato come valore predefinito, questo valore di mapping non supporta la specifica di un WS_DEFAULT_VALUE.


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


              <Struct>
    
              <sceltaA>123</choiceA>

              </Struct>

Struct S;
s.choice = ChoiceB;
s.value.b = ...; &virgolette; hello"


              <Struct>
    
              <sceltaB>hello</choiceB>

              </Struct>

Struct S;
s.choice = Nessuno;


              <Struct>

              </Struct>


Il valore del selettore indica quale dei campi dell'unione sono impostati. Gli altri campi vengono lasciati non inizializzati quando il valore viene deserializzato. Un'applicazione deve sempre consultare il valore del selettore per verificare che un campo dell'unione sia accessibile.
WS_REPEATING_ELEMENT_CHOICE_FIELD_MAPPING
Valore: 8
Il campo corrisponde a un set ripetuto di scelte di elementi.

Ogni elemento è rappresentato da un'unione con il valore del selettore. Questo mapping deve essere usato con WS_UNION_TYPE.

I valori localName/ns del campo vengono usati come nome dell'elemento XML e spazio dei nomi da utilizzare per l'elemento wrapper (l'elemento padre degli elementi ripetuti). Se non si desidera alcun elemento wrapper, entrambi localName/ns devono essere NULL.

Se è stato specificato un elemento wrapper, l'elemento wrapper deve essere visualizzato nel codice XML se il numero di elementi ripetuti non è 0. Non è possibile specificare un WS_DEFAULT_VALUE per questo mapping dei campi.

I campi itemLocalName e itemN devono essere NULL. Il nome e lo spazio dei nomi dell'elemento XML vengono definiti nel WS_UNION_DESCRIPTION.


Struct struct2
{
    Campo Struct* ; vedere WS_UNION_DESCRIPTION per la definizione di Struct
    Campo ULONGCount;
};

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

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

con l'elemento wrapper specificato

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

              </Struct2>

senza alcun elemento wrapper specificato

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

              </Struct2>


Il numero di elementi nella matrice deserializzata può essere vincolato specificando una strutturaWS_ITEM_RANGE null nonche fa parte del WS_FIELD_DESCRIPTION.
WS_ANY_ELEMENT_FIELD_MAPPING
Valore: 9
TBD
WS_REPEATING_ANY_ELEMENT_FIELD_MAPPING
Valore: 10
Il campo viene usato per eliminare o archiviare una sequenza di elementi con qualsiasi nome e spazio dei nomi.

Per archiviare gli elementi, è necessario usare un WS_XML_BUFFER_TYPE. Corrisponde a una matrice di WS_XML_BUFFER, come indicato di seguito:


Struct struct
{
    // ... campi noti ...
    WS_XML_BUFFER** campi;
    Campo ULONGCount;
    // ... campi noti ...
};

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


              <Struct>
    ... campi noti ...
    
              <sconosciuto1/>
    
              <sconosciuto2/>
    ... campi noti ...

              </Struct>


Per eliminare gli elementi, è necessario utilizzare un WS_VOID_TYPE. In questo caso, un campo non è obbligatorio nella struttura. Per altre informazioni, vedere WS_VOID_TYPE.

Il numero di elementi consentiti durante la deserializzazione può essere vincolato specificando una struttura diWS_ITEM_RANGE NULL nonche fa parte del WS_FIELD_DESCRIPTION.

Questo mapping non supporta la specifica di un WS_DEFAULT_VALUE.
WS_ANY_CONTENT_FIELD_MAPPING
Valore: 11
Il campo viene utilizzato per eliminare o archiviare qualsiasi contenuto rimanente (qualsiasi combinazione di testo o elementi) che si verifica prima della fine di un elemento.

Per archiviare gli elementi, è necessario usare un WS_XML_BUFFER_TYPE, come indicato di seguito:


Struct struct
{
    // ... campi noti ...
    WS_XML_BUFFER* campo;
};

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


              <Struct>
    ... campi noti ...
    text1
    
              <sconosciuto1/>
    text2
    
              <sconosciuto2/>

              </Struct>


Per eliminare gli elementi, è necessario utilizzare un WS_VOID_TYPE. In questo caso, un campo non è obbligatorio nella struttura. Per altre informazioni, vedere WS_VOID_TYPE.

Questo mapping non supporta la specifica di un WS_DEFAULT_VALUE.
WS_ANY_ATTRIBUTES_FIELD_MAPPING
Valore: 12
Il campo viene usato per eliminare o archiviare gli attributi di cui non è stato eseguito il mapping utilizzando altri valori di WS_FIELD_MAPPING.

Se questo mapping dei campi non viene specificato, gli attributi non mappati genereranno un errore durante la deserializzazione.

Il campo nome del WS_FIELD_DESCRIPTION deve essere NULL.

Il campo ns della WS_FIELD_DESCRIPTION limita lo spazio dei nomi degli attributi consentiti nel modo seguente:


  • Se il campo ns è NULL, non esiste alcuna restrizione. Le
    WS_FIELD_OTHER_NAMESPACE'opzione campo non deve essere impostata in questo caso.

  • Se il campo ns non èNULLe l'opzione campo
    WS_FIELD_OTHER_NAMESPACE non è impostato per il campo, quindi
    L'attributo deve avere lo stesso spazio dei nomi specificato nel campo ns.

  • Se il campo ns non èNULLe l'opzione campo
    WS_FIELD_OTHER_NAMESPACE è impostato per il campo, quindi
    l'attributo deve avere uno spazio dei nomi diverso da quello specificato
    nel campo ns.



Per archiviare gli attributi, è necessario usare WS_ANY_ATTRIBUTES_TYPE. Corrisponde a WS_ANY_ATTRIBUTES come indicato di seguito:


Struct struct
{
    // ... attributi noti ...
    WS_ANY_ATTRIBUTES campo;
    // ... altro contenuto ...
};

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

Struct <
    ... attributi noti ... 
    xmlns:a='http://example.com' a:unknown='value'>

    ... altro contenuto ...

              </Struct>


Per eliminare gli attributi non mappati, è necessario usare un WS_VOID_TYPE. In questo caso, un campo non è obbligatorio nella struttura. Per altre informazioni, vedere WS_VOID_TYPE.

Questo mapping non supporta la specifica di un WS_DEFAULT_VALUE.

Osservazioni

Il WS_FIELD_MAPPING indica il mapping di parti diverse del contenuto XML ai campi di una struttura. Ad esempio, WS_ELEMENT_FIELD_MAPPING può essere usato per eseguire il mapping del valore di un elemento figlio e WS_ATTRIBUTE_FIELD_MAPPING può essere usato per eseguire il mapping di un attributo. Qualsiasi contenuto XML letto non mappato in modo esplicito causerà la restituzione di WS_E_INVALID_FORMAT quando il codice XML viene deserializzato (vedere i valori restituiti da Servizi Web Windows.)

L'ordine del WS_FIELD_DESCRIPTION all'interno di un WS_STRUCT_DESCRIPTION è determinato dal valore WS_FIELD_MAPPING del WS_FIELD_DESCRIPTION. Per altre informazioni sull'ordinamento, vedere WS_STRUCT_DESCRIPTION.

Fabbisogno

Requisito Valore
client minimo supportato Windows 7 [solo app desktop]
server minimo supportato Windows Server 2008 R2 [solo app desktop]
intestazione webservices.h