enumeración WS_READ_OPTION (webservices.h)

  • Artículo

Especifica si se requiere un valor y cómo se debe asignar el valor.

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
Valor: 1
La opción especifica que el valor debe existir en el contenido XML.


El autor de la llamada debe especificar el almacenamiento en el que se va a leer el tipo de nivel superior.


El tamaño del almacenamiento especificado por el llamador varía según el tipo.
que se deserializa, como se indica a continuación:

  • Para primitivos (como WS_INT32_TYPE), el almacenamiento debe
    ser el tamaño del primitivo. En este caso, no es necesario especificar el montón.

  • Para las estructuras (si las definidas por el usuario que usan WS_STRUCT_TYPE,
    o predefinidos como WS_STRING), el almacenamiento debe ser el
    tamaño exacto de la estructura.
    Tenga en cuenta que los campos de la estructura que apuntan a otros datos siguen siendo necesarios para
    se asignará desde el WS_HEAP. Si no existe ningún campo para el
    estructura específica y, a continuación, no es necesario especificar el montón.




Tipos de puntero (WS_WSZ_TYPE y WS_XML_BUFFER_TYPE),
no se puede usar con WS_READ_REQUIRED_VALUE. El WS_READ_REQUIRED_POINTER
se debe usar value en su lugar.


Si el valor no está presente en el XML que se está leyendo,
Se devolverá un error de WS_E_INVALID_FORMAT .
(Vea Valores devueltos de servicios web de Windows).
WS_READ_REQUIRED_POINTER
Valor: 2
La opción especifica que el valor debe existir en el contenido XML.


El valor deserializado siempre se asigna en el WS_HEAP, independientemente de su tamaño.
Se devuelve el puntero al valor deserializado. Al usar esta opción,
el autor de la llamada debe pasar la dirección de un puntero y el tamaño de un puntero,
independientemente del tipo que se deserialice.


Si el valor no está presente, se devolverá un error.
Null nunca se devolverá cuando se use esta opción. Si el parámetro
value es opcional, use WS_READ_OPTIONAL_POINTER.
WS_READ_OPTIONAL_POINTER
Valor: 3
La opción especifica que el valor no necesita existir en el contenido XML.


El valor deserializado siempre se asigna en el WS_HEAP, independientemente de su tamaño.
Se devuelve el puntero al valor deserializado. Al usar esta opción,
el autor de la llamada debe pasar la dirección de un puntero y el tamaño de un puntero,
independientemente del tipo que se deserialice.


Si el valor no está presente en el XML que se está leyendo, la función realizará
succeed y NULL se devolverán para el valor .


Una aplicación que use esta opción debe tener cuidado de comprobar si hay VALORES NULL antes de acceder al valor.
Si nunca se espera un valor NULL , use WS_READ_REQUIRED_POINTER.
WS_READ_NILLABLE_POINTER
Valor: 4
La opción especifica que el valor puede ser nulo o que falte en el contenido XML.


El valor deserializado siempre se asigna en el WS_HEAP, independientemente de su tamaño.
Se devuelve el puntero al valor deserializado. Al usar esta opción,
el autor de la llamada debe pasar la dirección de un puntero y el tamaño de un puntero,
independientemente del tipo que se deserialice.


Si el elemento es nulo o falta en el XML que se está leyendo, la función se realizará correctamente y
Se devolverá un puntero NULL .
Si el elemento no es nulo en el XML que se lee, el valor se devuelve normalmente.


Una aplicación que use esta opción debe tener cuidado de comprobar si hay VALORES NULL antes de acceder al valor.
Si nunca se espera un valor NULL , use WS_READ_REQUIRED_POINTER.


Esta opción no se admite en combinación con WS_TYPE_MAPPING en las API.
que lee XML, incluidas las llamadas A WsReadType y WsReadElement .
WS_READ_NILLABLE_VALUE
Valor: 5
La opción especifica que el valor puede ser nulo o que falte en el contenido XML.


El autor de la llamada debe especificar el almacenamiento en el que se va a leer el tipo de nivel superior.


Si el elemento XML es nulo o falta, se devuelve un valor nulo. Si el elemento XML es
no nulo y, a continuación, el valor se deserializa normalmente.


Esta opción no se admite en combinación con WS_TYPE_MAPPING en las API.
que lee XML, incluidas las llamadas A WsReadType y WsReadElement .


Esta opción solo se admite para los siguientes tipos, que se enumeran a continuación,
que tienen una manera intrínseca de representar un valor nulo. Consulte la documentación
para cada tipo para obtener información sobre cómo se representa el valor nulo.

Comentarios

Cada WS_READ_OPTION describe cuándo se debe especificar un objeto WS_HEAP . En función de la función, es posible pasar un parámetro de montón NULL en este caso; consulte la documentación de la función específica para obtener más información sobre si se usa un montón predeterminado si el parámetro del montón es NULL.

A continuación se muestran aspectos que se deben tener en cuenta al deserializar valores en un objeto de montón (WS_HEAP):

  • Los valores deserializados permanecen asignados hasta que el montón se libera (WsFreeHeap) o se restablece (WsResetHeap).
  • Cada vez que se deserializan los valores, se anexan al montón (en lugar de reemplazar los valores existentes).
  • Si se producen errores durante la función de deserialización y se produce un error en la función, la memoria asignada desde el objeto del montón hasta que no se libere el error.
  • El tamaño del montón se puede usar para limitar las asignaciones totales realizadas durante la deserialización. El tamaño máximo del montón se puede determinar de la siguiente manera:
    • Determine el tamaño máximo, en bytes, de cada valor que se asignará en el montón durante la deserialización. Recuerde tener en cuenta que los tamaños de las estructuras de datos deserializadas pueden variar según la plataforma.
    • Cada matriz se considera un valor. Tenga en cuenta que el tamaño real de un elemento de la matriz puede verse afectado por la alineación necesaria del elemento.
    • Redondea el tamaño máximo de cada valor a un límite de 16 bytes.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 7 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2008 R2 [aplicaciones de escritorio | Aplicaciones para UWP]
Encabezado webservices.h