WsStartWriterCanonicalization function

Starts canonicalization on the specified XML writer.

Syntax

HRESULT WINAPI  WsStartWriterCanonicalization(
  _In_     WS_XML_WRITER*                          writer,
  _In_     WS_WRITE_CALLBACK                       writeCallback,
  _In_     void*                                   writeCallbackState,
           const WS_XML_CANONICALIZATION_PROPERTY* properties,
  _In_     ULONG                                   propertyCount,
  _In_opt_ WS_ERROR*                               error
);

Parameters

writer [in]

The XML writer on which canonicalization should be started.

writeCallback [in]

The callback that to be invoked to write the canonical bytes as they are generated. This callback will always be invoked synchronously.

writeCallbackState [in]

Caller-defined state that should be passed when invoking the WS_WRITE_CALLBACK.

properties

An array of optional properties controlling how canonicalization is to be performed. See WS_XML_CANONICALIZATION_PROPERTY.

propertyCount [in]

The number of properties.

error [in, optional]

Specifies where additional error information should be stored if the function fails.

Return value

This function can return one of these values.

Remarks

The usage pattern for canonicalization is to:

• call WsStartWriterCanonicalization,
• write the xml to be canonicalized,
• call WsEndWriterCanonicalization.

WsEndWriterCanonicalization must be called in order to ensure that all canonicalized bytes are written to the specified callback.

WsEndWriterCanonicalization must be called at the same depth at which WsStartWriterCanonicalization was called. Other writer APIs will return an error if it would move to a depth lower than where WsStartWriterCanonicalization was called.

It is an invalid operation to call WsMoveWriter or WsSetWriterPosition on a writer between a pair of matching WsStartWriterCanonicalization and WsEndWriterCanonicalization calls.

Calls to this API cannot be nested. So, a call to WsStartWriterCanonicalization must be followed by a call to WsEndWriterCanonicalization before the next WsStartWriterCanonicalization call.

If a WS_XML_CANONICALIZATION_ALGORITHM is not specified, then WS_EXCLUSIVE_XML_CANONICALIZATION_ALGORITHM is used.

The WS_INCLUSIVE_XML_CANONICALIZATION_ALGORITHM and WS_INCLUSIVE_WITH_COMMENTS_XML_CANONICALIZATION_ALGORITHM algorithms can only be used with entire xml documents. The writer must positioned at WS_XML_NODE_TYPE_BOF when WsStartWriterCanonicalization is called with these algorithms.

Requirements