Expand Minimize

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.

Return codeDescription
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:

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

Minimum supported client

Windows 7 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2 [desktop apps | Windows Store apps]

Header

WebServices.h

Library

WebServices.lib

DLL

WebServices.dll

 

 

Community Additions

ADD
Show:
© 2014 Microsoft