WS_XML_WRITER_PROPERTY_ID webservices.h) (列舉

  • 發行項

每個 xml 寫入器屬性都是由標識碼識別，並具有相關聯的值。 這個列舉用於 WS_XML_WRITER_PROPERTY 結構內，此結構用來做為 WsCreateWriter、WsSetOutput、WsSetOutputToBuffer 和 WsWriteXmlBufferToBytes 的參數。 它也直接作為 WsGetWriterProperty 的參數使用。

Syntax

typedef enum {
  WS_XML_WRITER_PROPERTY_MAX_DEPTH = 0,
  WS_XML_WRITER_PROPERTY_ALLOW_FRAGMENT = 1,
  WS_XML_WRITER_PROPERTY_MAX_ATTRIBUTES = 2,
  WS_XML_WRITER_PROPERTY_WRITE_DECLARATION = 3,
  WS_XML_WRITER_PROPERTY_INDENT = 4,
  WS_XML_WRITER_PROPERTY_BUFFER_TRIM_SIZE = 5,
  WS_XML_WRITER_PROPERTY_CHARSET = 6,
  WS_XML_WRITER_PROPERTY_BUFFERS = 7,
  WS_XML_WRITER_PROPERTY_BUFFER_MAX_SIZE = 8,
  WS_XML_WRITER_PROPERTY_BYTES = 9,
  WS_XML_WRITER_PROPERTY_IN_ATTRIBUTE = 10,
  WS_XML_WRITER_PROPERTY_MAX_MIME_PARTS_BUFFER_SIZE = 11,
  WS_XML_WRITER_PROPERTY_INITIAL_BUFFER = 12,
  WS_XML_WRITER_PROPERTY_ALLOW_INVALID_CHARACTER_REFERENCES = 13,
  WS_XML_WRITER_PROPERTY_MAX_NAMESPACES = 14,
  WS_XML_WRITER_PROPERTY_BYTES_WRITTEN = 15,
  WS_XML_WRITER_PROPERTY_BYTES_TO_CLOSE = 16,
  WS_XML_WRITER_PROPERTY_COMPRESS_EMPTY_ELEMENTS = 17,
  WS_XML_WRITER_PROPERTY_EMIT_UNCOMPRESSED_EMPTY_ELEMENTS = 18
} WS_XML_WRITER_PROPERTY_ID;

常數

 
WS_XML_WRITER_PROPERTY_MAX_DEPTH
值： 0
ULONG，指定寫入器允許的檔最大深度。


深度會以巢狀起始元素的數目來測量任何時間點。


深度 0 可防止寫入任何起始元素。


此屬性預設為 32。
WS_XML_WRITER_PROPERTY_ALLOW_FRAGMENT
值： 1
WS_XML_WRITER_MTOM_ENCODING 結構，指定寫入器是否允許檔最上層的多個元素和非空格符。 此屬性
可能無法使用 WS_XML_WRITER_MTOM_ENCODING 設定為TRUE。


此屬性預設為 FALSE。
WS_XML_WRITER_PROPERTY_MAX_ATTRIBUTES
值： 2
指定 ULONG 的 ULONG
寫入器在項目上允許的屬性數目上限。


此屬性預設為 128。
WS_XML_WRITER_PROPERTY_WRITE_DECLARATION
值： 3
BOOL，指定寫入器是否應該在檔開頭髮出適當的 xml 宣告。


此屬性預設為 FALSE。
WS_XML_WRITER_PROPERTY_INDENT
值： 4
ULONG，指定應該使用多少空格來格式化 xml。 如果縮排為零，則不會發生格式設定。


此屬性預設為 0。
WS_XML_WRITER_PROPERTY_BUFFER_TRIM_SIZE
值： 5
指定下列其中一項的 ULONG 。

如果寫入器使用 WS_XML_WRITER_BUFFER_OUTPUT，則此屬性是位元組數目上限
寫入器會保留 對 WsSetOutput 的呼叫，以供緩衝輸出之用。


如果寫入器使用 WS_XML_WRITER_STREAM_OUTPUT，則此屬性是位元組數目上限
寫入器會在對 WsSetOutput 和 WsFlushWriter 的呼叫之間保留
緩衝輸出的目的。


使用 WsSetOutputToBuffer 指定時，這個屬性不會有任何作用。


此屬性預設為 4096。
WS_XML_WRITER_PROPERTY_CHARSET
值： 6
WS_CHARSET值
會傳回寫入器用來編碼檔的字元集。 此值僅適用於
文字檔。
WS_XML_WRITER_PROPERTY_BUFFERS
值： 7
WS_BUFFERS結構
，傳回包含所產生 xml 位元組的一組緩衝區。


如果寫入器使用 WS_XML_WRITER_BUFFER_OUTPUT，則會傳回所有產生的位元組，然後
緩衝區有效，直到呼叫 WsSetOutput 或 WsFreeWriter 為止。


如果寫入器使用 WS_XML_WRITER_MTOM_ENCODING，則不得有開啟的專案。
支援的MIME元件將產生並包含在傳回的緩衝區中。 一旦完成此動作
發生於嘗試進一步寫入 xml 檔的任何 API 都會傳回 WS_E_INVALID_OPERATION。
(請參閱 Windows Web 服務傳回值。)

使用 WS_XML_WRITER_STREAM_OUTPUT 時無法使用這個屬性。


這個屬性不適用於設定為 WS_XML_BUFFER的寫入器。


這可能較不方便，但比使用 WS_XML_WRITER_PROPERTY_BYTES 更有效率，因為
寫入器不需要將組成檔的緩衝區串連成單一緩衝區。
WS_XML_WRITER_PROPERTY_BUFFER_MAX_SIZE
值： 8
ULONG
指定寫入器將緩衝的位元組數目上限。


如果寫入器使用 WS_XML_WRITER_BUFFER_OUTPUT，則這是最大數目
將緩衝處理整個檔的位元組。 對 WsFlushWriter 的呼叫沒有任何作用。


如果寫入器使用 WS_XML_WRITER_STREAM_OUTPUT，則這是 的最大數量
將在 WsFlushWriter 呼叫之間緩衝的數據。


使用 WsSetOutputToBuffer 指定時，這個屬性不會有任何作用。
WS_XML_WRITER_PROPERTY_BYTES
值： 9
WS_BUFFERS結構
，傳回包含所產生 xml 位元組的單一緩衝區。


如果寫入器使用 WS_XML_WRITER_BUFFER_OUTPUT，則會傳回所有產生的位元組，然後
緩衝區有效，直到呼叫 WsSetOutput 或 WsFreeWriter 為止。


如果寫入器使用 WS_XML_WRITER_MTOM_ENCODING，則不得有開啟的專案。
支援的MIME元件將產生並包含在傳回的緩衝區中。 一旦完成此動作
發生於嘗試進一步寫入 xml 檔的任何 API 都會傳回 WS_E_INVALID_OPERATION。


使用 WS_XML_WRITER_STREAM_OUTPUT 時無法使用這個屬性。


這個屬性不適用於設定為 WS_XML_BUFFER的寫入器。


這可能比使用 WS_XML_WRITER_PROPERTY_BUFFERS 更有效率，因為
寫入器可能需要將組成檔的緩衝區串連成單一緩衝區。
WS_XML_WRITER_PROPERTY_IN_ATTRIBUTE
值： 10
BOOL
表示已呼叫 WsWriteStartAttribute ，且寫入器為
位於屬性內容上。
WS_XML_WRITER_PROPERTY_MAX_MIME_PARTS_BUFFER_SIZE
值： 11
搭配 WS_XML_WRITER_MTOM_ENCODING 使用的 ULONG。 這會指定的最大數據量
將會緩衝處理以用於寫入MIME元件。 WsWriteBytes 和
WsPullBytes 需要緩衝數據，才能以個別MIME元件的形式發出數據
遵循檔，這可用來限制緩衝處理多少。


此屬性預設為 65536。
WS_XML_WRITER_PROPERTY_INITIAL_BUFFER
值： 12
包含寫入器可用於編碼 xml 檔的緩衝區 WS_BYTES 結構。 This is
當已知所產生 XML 數據的大小上限，或呼叫端想要擁有時，會很有用
放置位元組的緩衝區。


如果指定的大小大於或等於 WS_XML_WRITER_PROPERTY_BUFFER_MAX_SIZE，則 為
寫入器不會從其內部緩衝區配置。


這個緩衝區可能會顯示為屬性傳回的其中一個緩衝區 ，WS_XML_WRITER_PROPERTY_BUFFERS 或 WS_XML_WRITER_PROPERTY_BYTES。


呼叫端必須確定指定的緩衝區在寫入器的存留期內有效。
WS_XML_WRITER_PROPERTY_ALLOW_INVALID_CHARACTER_REFERENCES
值： 13
與WS_XML_WRITER_TEXT_ENCODING搭配使用的BOOL。 將此設定為 TRUE 允許字元參考
XML 1.0 視為無效的字元，


將此屬性設定為 TRUE 可能會影響互操作性。


此屬性預設為 FALSE。
WS_XML_WRITER_PROPERTY_MAX_NAMESPACES
值： 14
ULONG，指定在任何時間點可能出現在範圍中的 xmlns 唯一宣告數目上限
撰寫檔時。


此屬性預設為 32。
WS_XML_WRITER_PROPERTY_BYTES_WRITTEN
值： 15
指定下列其中一項的 ULONG 。

如果寫入器使用 WS_XML_WRITER_BUFFER_OUTPUT，則此屬性
會傳回已寫入器的位元組數目。


如果寫入器使用 WS_XML_WRITER_STREAM_OUTPUT，則此屬性
會傳回自上次呼叫 之後寫入器的位元組數目
WsFlushWriter。


如果寫入器目前正在寫入項目開始標記，則開始標籤的大小不會包含在中
傳回的值。


這個屬性不適用於使用 WsSetOutputToBuffer 設定的寫入器。
WS_XML_WRITER_PROPERTY_BYTES_TO_CLOSE
值： 16
ULONG，會傳回關閉任何開啟專案所需的最大位元組數目。


應用程式可以使用 WS_XML_WRITER_PROPERTY_BYTES_WRITTEN 和
WS_XML_WRITER_PROPERTY_BYTES_TO_CLOSE 大約額外多少
數據可能會寫入檔。 這樣做時，應用程式應該考慮
正在寫入之文件的編碼方式。


這個屬性不適用於使用 WsSetOutputToBuffer 設定的寫入器。
WS_XML_WRITER_PROPERTY_COMPRESS_EMPTY_ELEMENTS
值： 17
BOOL，可控制 WsCopyNode 如何複製沒有內容的元素。


當此屬性設定為 FALSE 時， WsCopyNode 會保留每個元素是否代表
做為開始/結束標記組，或做為空元素。 當此屬性設定為 TRUE時， WsCopyNode 將會
將沒有內容的元素轉換成空白專案。


二進位編碼不支援空的專案。 搭配使用 WsCopyNode 時
使用二進位編碼的寫入器這個屬性沒有任何作用。 所有空白元素都是
轉換成沒有內容的元素。


根據預設，此屬性為 FALSE。


針對輸入 XML 字串，例如：



syntax<br><br>&lt;?xml version="1.0" encoding="utf-8"?&gt;<br>&lt;container&gt;<br> &lt;emptyElement /&gt;<br> &lt;emptyElementWithEndTag&gt;&lt;/emptyElementWithEndTag&gt;<br>&lt;/container&gt;<br>

如果此屬性為 FALSE，WsCopyNode 將會產生下列 xml：




syntax<br><br>&lt;?xml version="1.0" encoding="utf-8"?&gt;<br>&lt;container&gt;<br> &lt;emptyElement /&gt;<br> &lt;emptyElementWithEndTag&gt;&lt;/emptyElementWithEndTag&gt;<br>&lt;/container&gt;<br>

如果此屬性為TRUE，WsCopyNode 將會產生下列 xml：



syntax<br><br>&lt;?xml version="1.0" encoding="utf-8"?&gt;<br>&lt;container&gt;<br> &lt;emptyElement /&gt;<br> &lt;emptyElementWithEndTag /&gt;<br>&lt;/container&gt;<br>
WS_XML_WRITER_PROPERTY_EMIT_UNCOMPRESSED_EMPTY_ELEMENTS
值： 18
Windows 8 或更新版本：控制如何發出空白專案的BOOL。

如果設定為 FALSE，則只會呼叫 WsWriteStartElement 和 WsWriteEndElement 所建立的專案，如下所示發出：


syntax<br>&lt;emptyElement /&gt;<br>

如果設定為 TRUE，則會發出該專案，如下所示：


xml<br><emptyElement></emptyElement><br><br>


預設值為 FALSE

規格需求

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