énumération WS_READ_OPTION (webservices.h)

  • Article

Spécifie si une valeur est requise et comment la valeur doit être allouée.

Syntax

typedef enum {
  WS_READ_REQUIRED_VALUE = 1,
  WS_READ_REQUIRED_POINTER = 2,
  WS_READ_OPTIONAL_POINTER = 3,
  WS_READ_NILLABLE_POINTER = 4,
  WS_READ_NILLABLE_VALUE = 5
} WS_READ_OPTION;

Constantes

 
WS_READ_REQUIRED_VALUE
Valeur : 1
L’option spécifie que la valeur doit exister dans le contenu XML.


L’appelant doit spécifier le stockage dans lequel lire le type de niveau supérieur.


La taille du stockage spécifiée par l’appelant varie en fonction du type
étant désérialisé, comme suit :

  • Pour les primitives (telles que WS_INT32_TYPE), le stockage doit
    soit la taille de la primitive. Dans ce cas, le tas n’a pas besoin d’être spécifié.

  • Pour les structures (si l’utilisateur a défini celles qui utilisent WS_STRUCT_TYPE,
    ou prédéfinis comme WS_STRING), le stockage doit être le
    taille exacte de la structure.
    Notez que les champs de la structure qui pointent vers d’autres données sont toujours requis pour
    être alloués à partir du WS_HEAP. S’il n’existe aucun champ pour le
    structure spécifique, le tas n’a pas besoin d’être spécifié.




Types de pointeurs (WS_WSZ_TYPE et WS_XML_BUFFER_TYPE),
ne peut pas être utilisé avec WS_READ_REQUIRED_VALUE. Le WS_READ_REQUIRED_POINTER
la valeur doit être utilisée à la place.


Si la valeur n’est pas présente dans le code XML en cours de lecture,
une erreur de WS_E_INVALID_FORMAT sera retournée.
(Voir Valeurs de retour des services web Windows.)
WS_READ_REQUIRED_POINTER
Valeur : 2
L’option spécifie que la valeur doit exister dans le contenu XML.


La valeur désérialisée est toujours allouée sur le WS_HEAP, quelle que soit sa taille.
Le pointeur vers la valeur désérialisée est retourné. Lorsque vous utilisez cette option,
l’appelant doit passer l’adresse d’un pointeur et la taille d’un pointeur,
quel que soit le type en cours de désérialisation.


Si la valeur n’est pas présente, une erreur est retournée.
La valeur NULL n’est jamais retournée lorsque cette option est utilisée. Si la
la valeur est facultative, utilisez WS_READ_OPTIONAL_POINTER.
WS_READ_OPTIONAL_POINTER
Valeur : 3
L’option spécifie que la valeur n’a pas besoin d’exister dans le contenu XML.


La valeur désérialisée est toujours allouée sur le WS_HEAP, quelle que soit sa taille.
Le pointeur vers la valeur désérialisée est retourné. Lorsque vous utilisez cette option,
l’appelant doit passer l’adresse d’un pointeur et la taille d’un pointeur,
quel que soit le type en cours de désérialisation.


Si la valeur n’est pas présente dans le code XML en cours de lecture, la fonction
réussite et null est retourné pour la valeur.


Une application qui utilise cette option doit veiller à case activée null avant d’accéder à la valeur.
Si une valeur NULL n’est jamais attendue, utilisez WS_READ_REQUIRED_POINTER.
WS_READ_NILLABLE_POINTER
Valeur : 4
L’option spécifie que la valeur peut être nulle ou manquante dans le contenu XML.


La valeur désérialisée est toujours allouée sur le WS_HEAP, quelle que soit sa taille.
Le pointeur vers la valeur désérialisée est retourné. Lorsque vous utilisez cette option,
l’appelant doit passer l’adresse d’un pointeur et la taille d’un pointeur,
quel que soit le type en cours de désérialisation.


Si l’élément est nul ou manquant dans le code XML en cours de lecture, la fonction réussit et
un pointeur NULL est retourné.
Si l’élément n’est pas nul dans le code XML en cours de lecture, la valeur est retournée normalement.


Une application qui utilise cette option doit veiller à case activée null avant d’accéder à la valeur.
Si une valeur NULL n’est jamais attendue, utilisez WS_READ_REQUIRED_POINTER.


Cette option n’est pas prise en charge en combinaison avec WS_TYPE_MAPPING dans les API
qui lisent du CODE XML, y compris les appels WsReadType et WsReadElement .
WS_READ_NILLABLE_VALUE
Valeur : 5
L’option spécifie que la valeur peut être nulle ou manquante dans le contenu XML.


L’appelant doit spécifier le stockage dans lequel lire le type de niveau supérieur.


Si l’élément XML est nul ou manquant, une valeur zéro est retournée. Si l’élément XML est
non nul, puis la valeur est désérialisée normalement.


Cette option n’est pas prise en charge en combinaison avec WS_TYPE_MAPPING dans les API
qui lisent du CODE XML, y compris les appels WsReadType et WsReadElement .


Cette option est uniquement prise en charge pour les types suivants, répertoriés ci-dessous,
qui ont une façon intrinsèque de représenter une valeur nulle. Consultez la documentation
pour chaque type pour obtenir des informations sur la façon dont zéro est représenté.

Remarques

Chaque WS_READ_OPTION indique quand un objet WS_HEAP doit être spécifié. Selon la fonction, il peut toujours être possible de passer un paramètre de tas NULL dans ce cas ; Consultez la documentation relative à la fonction spécifique pour plus d’informations sur l’utilisation d’un tas par défaut si le paramètre de tas a la valeur NULL.

Voici les éléments à prendre en compte lors de la désérialisation des valeurs dans un objet tas (WS_HEAP) :

  • Les valeurs désérialisées restent allouées jusqu’à ce que le tas soit libéré (WsFreeHeap) ou réinitialisé (WsResetHeap).
  • Chaque fois que les valeurs sont désérialisées, elles sont ajoutées au tas (au lieu de remplacer les valeurs existantes).
  • Si des erreurs sont rencontrées pendant la fonction de désérialisation et que la fonction échoue, la mémoire allouée à partir de l’objet tas jusqu’à ce que l’erreur ne soit pas libérée.
  • La taille du tas peut être utilisée pour limiter les allocations totales effectuées pendant la désérialisation. La taille maximale du tas peut être déterminée de la manière suivante :
    • Déterminez la taille maximale, en octets, de chaque valeur qui sera allouée sur le tas pendant la désérialisation. N’oubliez pas de tenir compte du fait que les tailles des structures de données désérialisées peuvent varier d’une plateforme à l’autre.
    • Chaque tableau est considéré comme une valeur. Notez que la taille réelle d’un élément dans le tableau peut être affectée par l’alignement requis de l’élément.
    • Arrondir la taille maximale de chaque valeur à une limite de 16 octets.

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]
En-tête webservices.h