Expand Minimize

WsStartReaderCanonicalization function

This operation begins the process of putting the specified XML Reader in a standard or "canonized" form.

The usage pattern for canonicalization is:

  • Move the Reader to the element where canonicalization begins.
  • Call WsStartReaderCanonicalization.
  • Move the Reader forward to the end position.
  • Call WsEndReaderCanonicalization.
During this process the canonical bytes are written to the specified writeCallback.

Note  Nodes advanced over are canonicalized including nodes of child elements skipped using WsSkipNode. This is beneficial because it means that canonicalization and parsing can be done in one pass over the XML content regardless of what functions are used to read the data.

In order to use the XML Reader solely for canonicalizing an XML element node the application can call WsStartReaderCanonicalization, WsSkipNode and WsEndReaderCanonicalization when the Reader is positioned on the element. WsEndReaderCanonicalization must be called in order to ensure that all canonicalized bytes are written to the specified callback.

Note  WsEndReaderCanonicalization must be called at the same depth at which WsStartReaderCanonicalization. Other reader functions return an error if moved to a depth lower than where WsStartReaderCanonicalization was called.

It is not valid to call WsMoveReader or WsSetReaderPosition on a Reader between calls to WsStartReaderCanonicalization and WsEndReaderCanonicalization.

Syntax


HRESULT WINAPI  WsStartReaderCanonicalization(
  _In_      WS_XML_READER* reader,
  _In_      WS_WRITE_CALLBACK writeCallback,
  _In_      void* writeCallbackState,
  const WS_XML_CANONICALIZATION_PROPERTY* properties,
  _In_      ULONG propertyCount,
  _In_opt_  WS_ERROR* error
);

Parameters

reader [in]

A pointer to the WS_XML_READER object on which canonicalization is started. The pointer must reference a valid XML Reader object.

writeCallback [in]

A callback function invoked to write the canonical bytes as they are generated.

Note  This callback is invoked synchronously.

writeCallbackState [in]

A pointer to a caller-defined state that is passed when invoking the WS_WRITE_CALLBACK.

properties

An "array" reference of optional properties controlling how canonicalization is performed.

Note  See WS_XML_CANONICALIZATION_PROPERTY for details.

propertyCount [in]

The number of properties.

error [in, optional]

A pointer to a WS_ERROR object where additional information about the error 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

Calls to this function cannot be nested. Consequently a call to WsStartReaderCanonicalization must be followed by a call to WsEndReaderCanonicalization before the next WsStartReaderCanonicalization call can be made.

If a WS_XML_CANONICALIZATION_ALGORITHM is not specified 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 Reader must be positioned at WS_XML_NODE_TYPE_BOF when WsStartReaderCanonicalization 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. All rights reserved.