WsStartWriterCanonicalization function (webservices.h)

Article
10/13/2021

Starts canonicalization on the specified XML writer.

Syntax

HRESULT WsStartWriterCanonicalization(
  [in]           WS_XML_WRITER                          *writer,
  [in]           WS_WRITE_CALLBACK                      writeCallback,
  [in]           void                                   *writeCallbackState,
                 const WS_XML_CANONICALIZATION_PROPERTY *properties,
  [in]           ULONG                                  propertyCount,
  [in, optional] WS_ERROR                               *error
);

Parameters

[in] writer

The XML writer on which canonicalization should be started.

[in] writeCallback

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

[in] writeCallbackState

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.

[in] propertyCount

The number of properties.

[in, optional] error

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

Return value

This function can return one of these values.

Return code	Description
E_INVALIDARG	One or more arguments are invalid.
WS_E_INVALID_OPERATION	The operation is not allowed due to the current state of the object.
WS_E_INVALID_FORMAT	The input data was not in the expected format or did not have the expected value.

Remarks

The usage pattern for canonicalization is to:

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

During this process, the canonical bytes will be written to the specified writeCallback. Every node written by the writer will be canonicalized. Thus, canonicalization and generation can be done in one pass over regardless of what APIs are used to write the XML. 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

Requirement	Value
Minimum supported client	Windows 7 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 R2 [desktop apps \| UWP apps]
Target Platform	Windows
Header	webservices.h
Library	WebServices.lib
DLL	WebServices.dll

Share via