Edit

Share via

WS_XML_WRITER_PROPERTY_ID enumeration (webservices.h)

  • Article

Each xml writer property is identified by an ID and has an associated value. This enumeration is used within the WS_XML_WRITER_PROPERTY structure, which is used as a parameter to WsCreateWriter, WsSetOutput, WsSetOutputToBuffer, and WsWriteXmlBufferToBytes. It is also used directly as a parameter to 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;

Constants

 
WS_XML_WRITER_PROPERTY_MAX_DEPTH
Value: 0
A ULONG that specifies the maximum depth of the document that the writer will permit.

Depth is measured at any point by the number of nested start elements.

A depth of 0 prevents any start elements from being written.

This property defaults to 32.
WS_XML_WRITER_PROPERTY_ALLOW_FRAGMENT
Value: 1
A WS_XML_WRITER_MTOM_ENCODING structure that specifies whether the writer will permit multiple elements and non-white space at the top level of the document. This property
may not be set to TRUE with WS_XML_WRITER_MTOM_ENCODING.

This property defaults to FALSE.
WS_XML_WRITER_PROPERTY_MAX_ATTRIBUTES
Value: 2
A ULONG that specifies
the maximum number of attributes the writer will permit on an element.

This property defaults to 128.
WS_XML_WRITER_PROPERTY_WRITE_DECLARATION
Value: 3
A BOOL that specifies if the writer should emit an appropriate xml declaration at the start of the document.

This property defaults to FALSE.
WS_XML_WRITER_PROPERTY_INDENT
Value: 4
A ULONG that specifies the how many spaces of indenting should be used to format the xml. If indent is zero, no formatting occurs.

This property defaults to 0.
WS_XML_WRITER_PROPERTY_BUFFER_TRIM_SIZE
Value: 5
A ULONG that specifies one of the following.

If the writer is using WS_XML_WRITER_BUFFER_OUTPUT, then this property is the maximum number of bytes
the writer will retain across calls to WsSetOutput for purposes of buffering output.

If the writer is using WS_XML_WRITER_STREAM_OUTPUT, then this property is the maximum number of bytes
the writer will retain across calls to WsSetOutput and WsFlushWriter for
purposes of buffering output.

This property has no effect when specified with WsSetOutputToBuffer.

This property defaults to 4096.
WS_XML_WRITER_PROPERTY_CHARSET
Value: 6
A WS_CHARSET value that
returns the character set the writer is using to encode the document. This value is only available for
text documents.
WS_XML_WRITER_PROPERTY_BUFFERS
Value: 7
A WS_BUFFERS structure
that returns a set of buffers containing the generated xml bytes.

If the writer is using WS_XML_WRITER_BUFFER_OUTPUT, then the all the generated bytes are returned, and
the buffers are valid until WsSetOutput or WsFreeWriter is called.

If the writer is using WS_XML_WRITER_MTOM_ENCODING, then there must be no open elements.
The supporting MIME parts will be generated and included in the returned buffers. Once this
occurs, any API that attempts to write further to the xml document will return WS_E_INVALID_OPERATION.
(See Windows Web Services Return Values.)

This property is not available when using WS_XML_WRITER_STREAM_OUTPUT.

This property is not available on a writer that is set to a WS_XML_BUFFER.

This may be less convenient but more efficient than using WS_XML_WRITER_PROPERTY_BYTES because the
writer does not have to concatenate the buffers that comprise the document into a single buffer.
WS_XML_WRITER_PROPERTY_BUFFER_MAX_SIZE
Value: 8
A ULONG that
specifies the maximum number of bytes the writer will buffer.

If the writer is using WS_XML_WRITER_BUFFER_OUTPUT, then this is the maximum number of
bytes that will buffered for the entire document. Calls to WsFlushWriter have no effect.

If the writer is using WS_XML_WRITER_STREAM_OUTPUT, then this is the maxmimum amount of
data that will be buffered between WsFlushWriter calls.

This property has no effect when specified with WsSetOutputToBuffer.
WS_XML_WRITER_PROPERTY_BYTES
Value: 9
A WS_BUFFERS structure
that returns a single buffer containing the generated xml bytes.

If the writer is using WS_XML_WRITER_BUFFER_OUTPUT, then all the generated bytes are returned, and
the buffer is valid until WsSetOutput or WsFreeWriter is called.

If the writer is using WS_XML_WRITER_MTOM_ENCODING, then there must be no open elements.
The supporting MIME parts will be generated and included in the returned buffers. Once this
occurs, any API that attempts to write further to the xml document will return WS_E_INVALID_OPERATION.

This property is not available when using WS_XML_WRITER_STREAM_OUTPUT.

This property is not available on a writer that is set to a WS_XML_BUFFER.

This may be more convenient but less efficient than using WS_XML_WRITER_PROPERTY_BUFFERS because the
writer may need to concatenate the buffers that comprise the document into a single buffer.
WS_XML_WRITER_PROPERTY_IN_ATTRIBUTE
Value: 10
A BOOL that
indicates that WsWriteStartAttribute has been called and the writer is
positioned on attribute content.
WS_XML_WRITER_PROPERTY_MAX_MIME_PARTS_BUFFER_SIZE
Value: 11
A ULONG used with WS_XML_WRITER_MTOM_ENCODING. This specifies the maximum amount of data that
will be buffered for purposes of writing the MIME parts. WsWriteBytes and
WsPullBytes need to buffer data in order to emit the data as a separate MIME part that
follows the document, and this can be used to limit how much is buffered.

This property defaults to 65536.
WS_XML_WRITER_PROPERTY_INITIAL_BUFFER
Value: 12
A WS_BYTES structure that contains a buffer that the writer may use for encoding the xml document. This is
useful when an upper bound on the size of the generated xml data is known, or the caller wants to own
the buffer in which the bytes are placed.

If the size specified is greater than or equal to WS_XML_WRITER_PROPERTY_BUFFER_MAX_SIZE, then the
writer will not allocate from its internal buffers.

This buffer may appear as one of the buffers returned by the property WS_XML_WRITER_PROPERTY_BUFFERS or WS_XML_WRITER_PROPERTY_BYTES.

The caller must ensure that the buffer specified is valid for the lifetime of the writer.
WS_XML_WRITER_PROPERTY_ALLOW_INVALID_CHARACTER_REFERENCES
Value: 13
A BOOL used with WS_XML_WRITER_TEXT_ENCODING. Setting this to TRUE permits character references
of characters considered invalid by XML 1.0 to be accepted.

Setting this property to TRUE may affect interoperability.

This property defaults to FALSE.
WS_XML_WRITER_PROPERTY_MAX_NAMESPACES
Value: 14
A ULONG that specifies the maximum number of xmlns unique declarations that may appear in scope at any point
while writing the document.

This property defaults to 32.
WS_XML_WRITER_PROPERTY_BYTES_WRITTEN
Value: 15
A ULONG that specifies one of the following.

If the writer is using WS_XML_WRITER_BUFFER_OUTPUT, then this property
returns the number of bytes that have been written to the writer.

If the writer is using WS_XML_WRITER_STREAM_OUTPUT, then this property
returns the number of bytes that have been written to the writer since the last call to
WsFlushWriter.

If the writer is currently writing an element start tag, then the size of the start tag is not included in
the value returned.

This property is not available on a writer that was set using WsSetOutputToBuffer.
WS_XML_WRITER_PROPERTY_BYTES_TO_CLOSE
Value: 16
A ULONG that returns the maximum number of bytes necessary to close any open elements.

An application can use WS_XML_WRITER_PROPERTY_BYTES_WRITTEN and
WS_XML_WRITER_PROPERTY_BYTES_TO_CLOSE to approximate how much additional
data may be written to the document. When doing so, the application should take into account
the encoding of the document being written.

This property is not available on a writer that was set using WsSetOutputToBuffer.
WS_XML_WRITER_PROPERTY_COMPRESS_EMPTY_ELEMENTS
Value: 17
A BOOL that controls how WsCopyNode copies elements with no content.

When this property is set to FALSE, WsCopyNode preserves whether each element is represented
as a start/end tag pair, or as an empty element. When this property is set to TRUE, WsCopyNode will
convert elements with no content to empty elements.

The binary encoding does not support empty elements. When using WsCopyNode with
a writer using the binary encoding this property has no effect either way. All empty elements are
converted into elements with no content.

By default, this property is FALSE.

For an input XML string like:



If this property is FALSE, WsCopyNode will generate the following xml:



If this property is TRUE, WsCopyNode will generate the following xml:

WS_XML_WRITER_PROPERTY_EMIT_UNCOMPRESSED_EMPTY_ELEMENTS
Value: 18
Windows 8 or later: A BOOL that controls how empty elements are emitted.

If set to FALSE, an element that is created by only calls to WsWriteStartElement and WsWriteEndElement will be emitted as follows:





If set to TRUE, that element will be emitted as follows:

xml



The default is FALSE

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 R2 [desktop apps | UWP apps]
Header webservices.h