WS_FIELD_MAPPING

フィールドは XML の type 属性 (xsi:type) に対応します。これは WS_DESCRIPTION_TYPE でのみ使用できます。

struct Base
{
    WS_STRUCT_DESCRIPTION* type;

    // ... base fields ...
};

struct Derived : Base
{
    // ... derived fields ...
};

struct Struct
{
    Base* field;
};

Derived derived;
derived.type = &DerivedStructDescription;
Struct s;
s.field = &derived;

<Struct>
    <field xsi:type='Derived'>
        // ... base fields ...
        // ... derived fields ...
    </field>
</Struct>

このマッピングでは WS_DEFAULT_VALUE の指定はサポートされません。

フィールドは 1 つの属性に対応します。

フィールドの localName/ns が XML 属性の名前と名前空間として使用されます。

指定がない限り、この属性は XML 内に存在しなければなりません。WS_FIELD_OPTIONAL が指定されている場合、この属性は XML 内に存在する必要はありません。省略可能で存在しない場合、フィールドには WS_DEFAULT_VALUE が設定されます。既定値が指定されていない場合は 0 が設定されます。

struct Struct
{
    int field;
};

Struct s;
s.field = 1;

<Struct field='1'/>

属性を破棄するには、WS_VOID_TYPE を使用してください。この場合、構造体にフィールドは必要ありません。詳細については WS_VOID_TYPE を参照してください。

フィールドは 1 つの要素に対応します。

フィールドの localName/ns が XML 要素の名前と名前空間として使用されます。

指定がない限り、この要素は XML 内に存在しなければなりません。WS_FIELD_OPTIONAL が指定されている場合、この要素は XML 内に存在する必要はありません。省略可能で存在しない場合、フィールドには WS_DEFAULT_VALUE が設定されます。既定値が指定されていない場合は 0 が設定されます。

struct Struct
{
    int field;
};

Struct s;
s.field = 1;

<Struct>
    <field>1</field>
</Struct>

要素を破棄するには、WS_VOID_TYPE を使用してください。この場合、構造体にフィールドは必要ありません。詳細については WS_VOID_TYPE を参照してください。

フィールドは繰り返される要素の集合に対応します。

フィールドの localName/ns は、ラッパー要素 (繰り返される要素の親となる要素) の XML 要素名と名前空間として使用されます。ラッパー要素が不要な場合は、localName/ns の両方を NULL にしてください。

ラッパー要素が指定されている場合、繰り返し要素の数が 0 でなければラッパー要素は XML 内に存在しなければなりません。このフィールドマッピングでは WS_DEFAULT_VALUE を指定できません。

itemLocalName と itemNs は、繰り返される要素の XML 要素名と名前空間として使用されます。

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

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

// with wrapper element specified
<Struct>
    <field>
        <item>1</item>
        <item>2</item>
    </field>
</Struct>

// with no wrapper element specified
<Struct>
    <item>1</item>
    <item>2</item>
</Struct>

逆シリアル化される配列の要素数は、WS_FIELD_DESCRIPTION の一部である WS_ITEM_RANGE 構造体を NULL 以外で指定することにより制限できます。

フィールドは要素の文字コンテンツ全体に対応します。このマッピングを使用する場合、子要素は許可されません。

このマッピングは通常、WS_ATTRIBUTE_FIELD_MAPPING と組み合わせて使用し、テキストと属性を含む (子要素は含まない) 要素に対応する構造体を定義します。

struct Struct
{
    int field;
};

Struct s;
s.field = 1;

<Struct>1</Struct>

このマッピングでは WS_DEFAULT_VALUE の指定はサポートされません。

フィールドはシリアル化も逆シリアル化もされません。

シリアル化時にはフィールドは無視され、逆シリアル化時には既定値で初期化されます。

フィールドが既存の型のいずれか (たとえば WS_INT32_TYPE) に対応する場合は、その型を指定できます。フィールドの型が既存の型のいずれでもない場合は、WS_VOID_TYPE を使用して任意の型とサイズのフィールドを指定できます。

逆シリアル化時にフィールドを初期化する値を指定するために、WS_DEFAULT_VALUE を指定できます。既定値が指定されていない場合、フィールドは 0 で初期化されます。

このフィールドマッピングは、WS_FIELD_OPTIONS の値が 0 の場合にのみ使用できます。

struct Struct
{
    int field;
};

Struct s;
s.field = 1;

<Struct/>

フィールドは予約済みの xml 属性 (xml:lang など) に対応します。

フィールドの localName が XML 属性名の識別に使用されます。

WS_FIELD_OPTIONAL が指定されていない限り、この属性は XML 内に存在しなければなりません。WS_FIELD_OPTIONAL が指定されている場合、この属性は XML 内に存在する必要はありません。省略可能で存在しない場合、フィールドには WS_DEFAULT_VALUE が設定されます。既定値が指定されていない場合は 0 が設定されます。

struct Struct
{
    WS_STRING field;
};

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

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

s.field = ...; // 'true'

// Example of xml:space
<Struct xml:space='true'>

フィールドは、複数の候補要素の中からの選択に対応します。各要素は共用体 (union) のいずれかのフィールドに対応します。共用体の各フィールドには対応する列挙値があり、現在の選択を識別するために使用されます。

// Enumeration of choices of different values
enum Choice
{
    ChoiceA = 10,
    ChoiceB = 20,
    None = 0,
};

// Struct containing union of values, and enum 'selector'
struct Struct
{
    Choice choice;
    union
    {
        int a;          // valid when choice is ChoiceA
        WS_STRING b;    // valid when choice is ChoiceB
    } value;
};                    

このフィールドマッピングは WS_UNION_TYPE と共に使用しなければなりません。選択肢となる要素の名前と名前空間は WS_UNION_DESCRIPTION で指定します。フィールドの localName と ns は NULL でなければなりません。

WS_FIELD_OPTIONAL が指定されていない限り、いずれかの要素が XML 内に存在しなければなりません。WS_FIELD_OPTIONAL が指定されている場合、いずれの要素も XML 内に存在する必要はありません。省略可能でいずれの要素も存在しない場合、フィールドのセレクター値は列挙型の none 値 (WS_UNION_DESCRIPTION の noneEnumValue フィールドで指定された値) に設定されます。nonEnumValue が既定値として使用されるため、このマッピング値では 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 = ...; // 'hello'

<Struct>
    <choiceB>hello</choiceB>
</Struct>

Struct S;
s.choice = None;

<Struct>
</Struct>                    

フィールドは、複数の候補要素の中からの選択に対応します。各要素は共用体 (union) のいずれかのフィールドに対応します。共用体の各フィールドには対応する列挙値があり、現在の選択を識別するために使用されます。

// Enumeration of choices of different values
enum Choice
{
    ChoiceA = 10,
    ChoiceB = 20,
    None = 0,
};

// Struct containing union of values, and enum "selector"
struct Struct
{
    Choice choice;
    union
    {
        int a;          // valid when choice is ChoiceA
        WS_STRING b;    // valid when choice is ChoiceB
    } value;
};

このフィールドマッピングは WS_UNION_TYPE と共に使用しなければなりません。選択肢となる要素の名前と名前空間は WS_UNION_DESCRIPTION で指定します。フィールドの localName と ns は NULL でなければなりません。

WS_FIELD_OPTIONAL が指定されていない限り、いずれかの要素が XML 内に存在しなければなりません。WS_FIELD_OPTIONAL が指定されている場合、いずれの要素も XML 内に存在する必要はありません。省略可能でいずれの要素も存在しない場合、フィールドのセレクター値は列挙型の none 値 (WS_UNION_DESCRIPTION の noneEnumValue フィールドで指定された値) に設定されます。nonEnumValue が既定値として使用されるため、このマッピング値では 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 = ...; // &quot;hello&quot;

<Struct>
    <choiceB>hello</choiceB>
</Struct>

Struct S;
s.choice = None;

<Struct>
</Struct>

セレクター値は、共用体のどのフィールドが設定されているかを示します。値が逆シリアル化されるとき、その他のフィールドは未初期化のまま残ります。アプリケーションは、共用体のフィールドにアクセスできるかどうかを確認するために、必ずセレクター値を参照してください。

フィールドは、繰り返される要素選択の集合に対応します。

各項目はセレクター値を持つ共用体で表されます。このマッピングは WS_UNION_TYPE と共に使用しなければなりません。

フィールドの localName/ns は、ラッパー要素 (繰り返される要素の親となる要素) の XML 要素名と名前空間として使用されます。ラッパー要素が不要な場合は、localName/ns の両方を NULL にしてください。

ラッパー要素が指定されている場合、繰り返し要素の数が 0 でなければラッパー要素は XML 内に存在しなければなりません。このフィールドマッピングでは WS_DEFAULT_VALUE を指定できません。

itemLocalName と itemNs のフィールドは NULL でなければなりません。XML 要素名と名前空間は WS_UNION_DESCRIPTION で定義されます。

struct Struct2
{
    Struct* field;      // see WS_UNION_DESCRIPTION for definition of Struct
    ULONG fieldCount;
};

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

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

// with wrapper element specified
<Struct2>
    <field>
        <item>123</item>
        <item>hello</item>
    </field>
</Struct2>

// with no wrapper element specified
<Struct2>
    <item>123</item>
    <item>hello</item>
</Struct2>

逆シリアル化される配列の要素数は、WS_FIELD_DESCRIPTION の一部である WS_ITEM_RANGE 構造体を NULL 以外で指定することにより制限できます。

フィールドは、任意の名前と名前空間を持つ一連の要素を破棄または格納するために使用されます。

要素を格納するには、WS_XML_BUFFER_TYPE を使用してください。これは次のように WS_XML_BUFFER の配列に対応します。

struct Struct
{
    // ... known fields ...
    WS_XML_BUFFER** fields;
    ULONG fieldCount;
    // ... known fields ...
};

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

<Struct>
    ... known fields ...
    <unknown1/>
    <unknown2/>
    ... known fields ...
</Struct>

要素を破棄するには、WS_VOID_TYPE を使用してください。この場合、構造体にフィールドは必要ありません。詳細については WS_VOID_TYPE を参照してください。

逆シリアル化時に許可される要素数は、WS_FIELD_DESCRIPTION の一部である WS_ITEM_RANGE 構造体を NULL 以外で指定することにより制限できます。

このマッピングでは WS_DEFAULT_VALUE の指定はサポートされません。

フィールドは、要素の終わりまでに現れる残りのコンテンツ (テキストと要素の任意の組み合わせ) を破棄または格納するために使用されます。

要素を格納するには、次のように WS_XML_BUFFER_TYPE を使用してください。

struct Struct
{
    // ... known fields ...
    WS_XML_BUFFER* field;
};

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

<Struct>
    ... known fields ...
    text1
    <unknown1/>
    text2
    <unknown2/>
</Struct>

要素を破棄するには、WS_VOID_TYPE を使用してください。この場合、構造体にフィールドは必要ありません。詳細については WS_VOID_TYPE を参照してください。

このマッピングでは WS_DEFAULT_VALUE の指定はサポートされません。

フィールドは、他の WS_FIELD_MAPPING の値ではマップされなかった属性を破棄または格納するために使用されます。

このフィールドマッピングが指定されていない場合、マップされていない属性があると逆シリアル化時にエラーが発生します。

WS_FIELD_DESCRIPTION の name フィールドは 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 に対応します。

struct Struct
{
    // ... known attributes ...
    WS_ANY_ATTRIBUTES field;
    // ... other content ...
};

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

<Struct 
    ... known attributes ... 
    xmlns:a='http://example.com' a:unknown='value'>

    ... other content ...
</Struct>

マップされていない属性を破棄するには、WS_VOID_TYPE を使用してください。この場合、構造体にフィールドは必要ありません。詳細については WS_VOID_TYPE を参照してください。

このマッピングでは WS_DEFAULT_VALUE の指定はサポートされません。