WsStartReaderCanonicalization, fonction (webservices.h)

Article
08/27/2023

Cette opération commence le processus de mise en place du lecteur XML spécifié dans un formulaire standard ou « canonisé ».

Le modèle d’utilisation pour la canonisation est le suivant :

Déplacez le lecteur vers l’élément où la canonisation commence.
Appelez WsStartReaderCanonicalization.
Déplacez le lecteur vers l’avant jusqu’à la position de fin.
Appelez WsEndReaderCanonicalization.

Au cours de ce processus, les octets canoniques sont écrits dans l’objet writeCallback spécifié.

Note Les nœuds avancés sur sont canonisés, y compris les nœuds d’éléments enfants ignorés à l’aide de WsSkipNode. Cela est bénéfique, car cela signifie que la canonisation et l’analyse peuvent être effectuées en une seule passe sur le contenu XML, quelles que soient les fonctions utilisées pour lire les données.

Afin d’utiliser le lecteur XML uniquement pour canoniser un nœud d’élément XML, l’application peut appeler WsStartReaderCanonicalization, WsSkipNode et WsEndReaderCanonicalization lorsque le lecteur est positionné sur l’élément.

WsEndReaderCanonicalization doit être appelé pour garantir que tous les octets canoniques sont écrits dans le rappel spécifié.

NoteWsEndReaderCanonicalization doit être appelé à la même profondeur que WsStartReaderCanonicalization. D’autres fonctions de lecteur retournent une erreur si elles sont déplacées vers une profondeur inférieure à l’emplacement où WsStartReaderCanonicalization a été appelé. d

Il n’est pas valide d’appeler WsMoveReader ou WsSetReaderPosition sur un lecteur entre les appels à WsStartReaderCanonicalization et WsEndReaderCanonicalization.

Syntaxe

HRESULT WsStartReaderCanonicalization(
  [in]           WS_XML_READER                          *reader,
  [in]           WS_WRITE_CALLBACK                      writeCallback,
  [in]           void                                   *writeCallbackState,
                 const WS_XML_CANONICALIZATION_PROPERTY *properties,
  [in]           ULONG                                  propertyCount,
  [in, optional] WS_ERROR                               *error
);

Paramètres

[in] reader

Pointeur vers l’objet WS_XML_READER sur lequel la canonicalisation est démarrée. Le pointeur doit référencer un objet Lecteur XML valide.

[in] writeCallback

Fonction de rappel appelée pour écrire les octets canoniques au fur et à mesure qu’ils sont générés.

Note Ce rappel est appelé de manière synchrone.

[in] writeCallbackState

Pointeur vers un état défini par l’appelant qui est passé lors de l’appel du WS_WRITE_CALLBACK.

properties

Référence « tableau » des propriétés facultatives contrôlant la façon dont la canonicalisation est effectuée.

Note Pour plus d’informations, consultez WS_XML_CANONICALIZATION_PROPERTY .

[in] propertyCount

Nombre de propriétés.

[in, optional] error

Pointeur vers un objet WS_ERROR où des informations supplémentaires sur l’erreur doivent être stockées en cas d’échec de la fonction.

Valeur retournée

Cette fonction peut retourner l’une de ces valeurs.

Code de retour	Description
E_INVALIDARG	Un ou plusieurs arguments ne sont pas valides.
WS_E_INVALID_OPERATION	L’opération n’est pas autorisée en raison de l’état actuel de l’objet.
WS_E_INVALID_FORMAT	Les données d’entrée n’étaient pas au format attendu ou n’avaient pas la valeur attendue.

Remarques

Les appels à cette fonction ne peuvent pas être imbriqués. Par conséquent, un appel à WsStartReaderCanonicalization doit être suivi d’un appel à WsEndReaderCanonicalization avant que l’appel WsStartReaderCanonicalization suivant puisse être effectué.

Si aucune WS_XML_CANONICALIZATION_ALGORITHM n’est spécifiée WS_EXCLUSIVE_XML_CANONICALIZATION_ALGORITHM est utilisée.

Les algorithmes WS_INCLUSIVE_XML_CANONICALIZATION_ALGORITHM et WS_INCLUSIVE_WITH_COMMENTS_XML_CANONICALIZATION_ALGORITHM ne peuvent être utilisés qu’avec des documents XML entiers. Le lecteur doit être positionné à WS_XML_NODE_TYPE_BOF lorsque WsStartReaderCanonicalization est appelé avec ces algorithmes.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	webservices.h
Bibliothèque	WebServices.lib
DLL	WebServices.dll

Partager via