共用方式為

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* 類型;

    // ...基底欄位...
};

結構衍生：基底
{
    // ...衍生欄位...
};

結構結構
{
    [基底*] 欄位;
};

衍生衍生;
derived.type = &DerivedStructDescription;
結構;
s.field = &衍生;


              <結構>
    
              <字段 xsi：type='Derived'>
        // ...基底欄位...
        // ...衍生欄位...
    
              </field>

              </結構>


這個對應不支援指定 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>

              </結構>


若要捨棄項目，應該使用 WS_VOID_TYPE。 在此情況下，結構中不需要欄位。 如需詳細資訊，請參閱 WS_VOID_TYPE。
WS_REPEATING_ELEMENT_FIELD_MAPPING
值：3
欄位會對應至一組重複的專案。

欄位的localName/ns會作為 XML 專案名稱和命名空間，用於包裝函式專案（這是重複元素的父元素）。 如果不需要包裝函式專案，則這兩個localName/ns都應該 NULL。

如果已指定包裝函式專案，如果重複專案計數不是 0，包裝函式專案必須出現在 XML 中。 此欄位對應可能未指定 WS_DEFAULT_VALUE。

itemLocalName 和 itemN 會當做重複專案的 XML 專案名稱和命名空間使用。


結構結構
{
    int* 欄位;
    ULONG fieldCount;
};

int values[] = { 1， 2 };
結構;
s.field = 值;
s.fieldCount = 2;

指定包裝函式專案

              <結構>
    [<] 欄位>
        
              <專案>1</item>
        
              <專案>2</item>
    
              </field>

              </結構>

未指定包裝函式專案

              <結構>
    
              <專案>1</item>
    
              <專案>2</item>

              </結構>


還原串行化陣列中的項目數目可以藉由指定非NULLWS_ITEM_RANGE 結構來限制，該結構是 WS_FIELD_DESCRIPTION的一部分。
WS_TEXT_FIELD_MAPPING
值：4
欄位會對應至專案的整個字元內容。 使用此對應時，不允許子專案。

此對應通常與 WS_ATTRIBUTE_FIELD_MAPPING 搭配使用，以定義結構，該結構會對應至包含某些文字和屬性的專案（但沒有子元素）。


結構結構
{
    int 欄位;
};

結構;
s.field = 1;


              <結構>1</結構>


這個對應不支援指定 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）。

欄位的localName是用來識別 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，
};

包含值聯集的結構，以及列舉 'selector'
結構結構
{
    選擇選擇;
    聯盟
    {
        int a;當選擇為 ChoiceA 時有效
        WS_STRING b;當選擇為 ChoiceB 時有效
    } 值;
};


此欄位對應必須與 WS_UNION_TYPE搭配使用。 項目選擇的名稱和命名空間會在 WS_UNION_DESCRIPTION中指定。 欄位的 localName 和 ns 應 NULL。

除非指定 WS_FIELD_OPTIONAL，否則其中一個項目必須出現在 XML 中。 如果指定 WS_FIELD_OPTIONAL，則不需要任何專案出現在 XML 中。 如果選擇性且沒有任何元素存在，則字段的選取器值會設定為列舉的無值（如 WS_UNION_DESCRIPTION的 noneEnumValue 字段所指定）。 由於 nonEnumValue 是當做預設值使用，所以這個對應值不支援指定 WS_DEFAULT_VALUE。


結構;
s.choice = ChoiceA;
s.value.a = 123;


              <結構>
    
              <choiceA>123</choiceA>

              </結構>

結構 S;
s.choice = ChoiceB;
s.value.b = ...;'你好'


              <結構>
    
              <choiceB>你好</choiceB>

              </結構>

結構 S;
s.choice = None;


              <結構>

              </結構>


欄位會對應至一組可能元素之間的選擇。 每個元素都會對應至聯集的其中一個字段。 聯集的每個欄位都有對應的列舉值，用來識別目前的選擇。


不同值的選項列舉
列舉選擇
{
    ChoiceA = 10，
    ChoiceB = 20，
    None = 0，
};

包含值聯集的結構，以及列舉 "selector"
結構結構
{
    選擇選擇;
    聯盟
    {
        int a;當選擇為 ChoiceA 時有效
        WS_STRING b;當選擇為 ChoiceB 時有效
    } 值;
};


此欄位對應必須與 WS_UNION_TYPE搭配使用。 項目選擇的名稱和命名空間會在 WS_UNION_DESCRIPTION中指定。 欄位的 localName 和 ns 應 NULL。

除非指定 WS_FIELD_OPTIONAL，否則其中一個項目必須出現在 XML 中。 如果指定 WS_FIELD_OPTIONAL，則不需要任何專案出現在 XML 中。 如果選擇性且沒有任何元素存在，則字段的選取器值會設定為列舉的無值（如 WS_UNION_DESCRIPTION的 noneEnumValue 字段所指定）。 由於 nonEnumValue 是當做預設值使用，所以這個對應值不支援指定 WS_DEFAULT_VALUE。


結構;
s.choice = ChoiceA;
s.value.a = 123;


              <結構>
    
              <choiceA>123</choiceA>

              </結構>

結構 S;
s.choice = ChoiceB;
s.value.b = ...;&引號;你好&引号;


              <結構>
    
              <choiceB>你好</choiceB>

              </結構>

結構 S;
s.choice = None;


              <結構>

              </結構>


選取器值表示已設定聯集的欄位。 當值還原串行化時，其他欄位會保持未初始化。 應用程式應該一律諮詢選取器值，以確認聯集的欄位是可存取的。
WS_REPEATING_ELEMENT_CHOICE_FIELD_MAPPING
值：8
欄位會對應至一組重複的項目選擇。

每個項目都會以具有選取器值的聯集來表示。 此對應必須與 WS_UNION_TYPE搭配使用。

欄位的localName/ns會作為 XML 專案名稱和命名空間，用於包裝函式專案（這是重複元素的父元素）。 如果不需要包裝函式專案，則這兩個localName/ns都應該 NULL。

如果已指定包裝函式專案，如果重複專案計數不是 0，包裝函式專案必須出現在 XML 中。 此欄位對應可能未指定 WS_DEFAULT_VALUE。

itemLocalName 和 itemN 字段必須 NULL。 XML 專案名稱和命名空間定義於 WS_UNION_DESCRIPTION中。


結構結構 2
{
    結構* 欄位;如需結構的定義，請參閱WS_UNION_DESCRIPTION
    ULONG fieldCount;
};

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

結構2 s2;
s2.field = 值;
s2.fieldCount = 2;

指定包裝函式專案

              <結構 2>
    [<] 欄位>
        
              <專案>123</item>
        
              <專案>你好</item>
    
              </field>

              </Struct2>

未指定包裝函式專案

              <結構 2>
    
              <專案>123</item>
    
              <專案>你好</item>

              </Struct2>


還原串行化陣列中的項目數目可以藉由指定非NULLWS_ITEM_RANGE 結構來限制，該結構是 WS_FIELD_DESCRIPTION的一部分。
WS_ANY_ELEMENT_FIELD_MAPPING
值：9
待定
WS_REPEATING_ANY_ELEMENT_FIELD_MAPPING
值：10
欄位可用來捨棄或儲存具有任何名稱和命名空間的專案序列。

若要儲存專案，應該使用 WS_XML_BUFFER_TYPE。 這會對應至 WS_XML_BUFFER的陣列，如下所示：


結構結構
{
    // ...已知欄位...
    WS_XML_BUFFER** 欄位;
    ULONG fieldCount;
    // ...已知欄位...
};

結構;
s.fields = ...;{ '<unknown1/>'， '<unknown2/>'; }
s.fieldCount = 2;


              <結構>
    ...已知欄位...
    
              <未知1/>
    
              <未知2/>
    ...已知欄位...

              </結構>


若要捨棄項目，應該使用 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/>

              </結構>


若要捨棄項目，應該使用 WS_VOID_TYPE。 在此情況下，結構中不需要欄位。 如需詳細資訊，請參閱 WS_VOID_TYPE。

這個對應不支援指定 WS_DEFAULT_VALUE。
WS_ANY_ATTRIBUTES_FIELD_MAPPING
值：12
欄位可用來捨棄或儲存未使用其他 WS_FIELD_MAPPING 值對應的任何屬性。

如果未指定此欄位對應，則還原串行化時，未對應的屬性會造成錯誤。

WS_FIELD_DESCRIPTION 的名稱字段必須 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，如下所示：


結構結構
{
    // ...已知屬性...
    WS_ANY_ATTRIBUTES欄位;
    // ...其他內容...
};

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


              <結構
    ...已知屬性...
    xmlns：a='http://example.com' a：unknown='value'>

    ...其他內容...

              </結構>


若要捨棄未對應的屬性，應該使用 WS_VOID_TYPE。 在此情況下，結構中不需要欄位。 如需詳細資訊，請參閱 WS_VOID_TYPE。

這個對應不支援指定 WS_DEFAULT_VALUE。

言論

WS_FIELD_MAPPING 會指出 XML 內容的不同部分如何對應至結構的欄位。 例如，WS_ELEMENT_FIELD_MAPPING 可用來對應子元素的值，而 WS_ATTRIBUTE_FIELD_MAPPING 可用來對應屬性。 任何未明確對應之讀取的 XML 內容，都會在還原串行化 XML 時 WS_E_INVALID_FORMAT 傳回 （請參閱 Windows Web Services 傳回值。

WS_STRUCT_DESCRIPTION 內的 WS_FIELD_DESCRIPTION 順序取決於 WS_FIELD_DESCRIPTION的 WS_FIELD_MAPPING 值。 如需訂購的詳細資訊，請參閱 WS_STRUCT_DESCRIPTION。

要求

要求 價值
最低支援的用戶端 Windows 7 [僅限傳統型應用程式]
支援的最低伺服器 Windows Server 2008 R2 [僅限傳統型應用程式]
標頭 webservices.h