Windows Dev Center

Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

WS_READ_OPTION enumeration

Specifies whether a value is required, and how the value should be allocated.

Syntax


enum WS_READ_OPTION {  WS_READ_REQUIRED_VALUE, 
  WS_READ_REQUIRED_POINTER, 
  WS_READ_OPTIONAL_POINTER, 
  WS_READ_NILLABLE_POINTER, 
  WS_READ_NILLABLE_VALUE 

};

Constants

WS_READ_REQUIRED_VALUE

The option specifies that the value must exist in the XML content.

The caller must specify the storage to read the top-level type into.

The size of the storage specified by the caller varies by the type being deserialized, as follows:

  • For primitives (such as WS_INT32_TYPE), the storage should be the size of the primitive. In this case, the heap does not need to be specified.
  • For structures (whether user defined ones that use WS_STRUCT_TYPE, or predefined ones like WS_STRING), the storage should be the exact size of the structure. Note that fields of the structure that point to other data is still required to be allocated from the WS_HEAP. If no fields exist for the specific structure, then the heap does not need to be specified.

Pointer types (WS_WSZ_TYPE and WS_XML_BUFFER_TYPE), may not be used with WS_READ_REQUIRED_VALUE. The WS_READ_REQUIRED_POINTER value should be used instead.

If the value is not present in the XML being read, a WS_E_INVALID_FORMAT error will be returned. (See Windows Web Services Return Values.)

WS_READ_REQUIRED_POINTER

The option specifies that the value must exist in the XML content.

The deserialized value is always allocated on the WS_HEAP, regardless of it's size. The pointer to the deserialized value is returned. When using this option, the caller should pass the address of a pointer, and size of a pointer, regardless of the type being deserialized.

If the value is not present, then an error will be returned. NULL will never be returned when this option is used. If the value is optional, use WS_READ_OPTIONAL_POINTER.

WS_READ_OPTIONAL_POINTER

The option specifies that the value need not exist in the XML content.

The deserialized value is always allocated on the WS_HEAP, regardless of it's size. The pointer to the deserialized value is returned. When using this option, the caller should pass the address of a pointer, and size of a pointer, regardless of the type being deserialized.

If the value is not present in the XML being read, the function will succeed and NULL will be returned for the value.

An application that uses this option should be careful to check for NULL before accessing the value. If a NULL value is never expected, use WS_READ_REQUIRED_POINTER.

WS_READ_NILLABLE_POINTER

The option specifies that the value may be nil or missing in the XML content.

The deserialized value is always allocated on the WS_HEAP, regardless of it's size. The pointer to the deserialized value is returned. When using this option, the caller should pass the address of a pointer, and size of a pointer, regardless of the type being deserialized.

If the element is nil or missing in the XML being read, the function will succeed and a NULL pointer will be returned. If the element is not nil in the XML being read, then the value is returned normally.

An application that uses this option should be careful to check for NULL before accessing the value. If a NULL value is never expected, use WS_READ_REQUIRED_POINTER.

This option is not supported in combination with WS_TYPE_MAPPING in APIs that read XML, inlcuding WsReadType and WsReadElement calls.

WS_READ_NILLABLE_VALUE

The option specifies that the value may be nil or missing in the XML content.

The caller must specify the storage to read the top-level type into.

If the XML element is nil or missing, then a nil value is returned. If the XML element is non-nil, then the value is deserialized normally.

This option is not supported in combination with WS_TYPE_MAPPING in APIs that read XML, inlcuding WsReadType and WsReadElement calls.

This option is only supported for the following types, listed below, which have a intrinsic way to represent a nil value. See the documentation for each type for information on how nil is represented.

Security

From a security perspective, it is useful to think of the deserialization process as a way for a remote party to specify how much memory to allocate on the local machine. If memory allocation is not appropriately limited, a remote attacker can use this to attempt a Denial of Service (DoS) attack.

There are two ways to limit how much memory may be allocated. These methods may be combined.

  • Specify a heap limit which corresponds to the maximum expected size in bytes of the data that will be deserialized. See the Remarks section for how to choose this size based on the specific data structure being deserialized.
  • For each value being deserialized, specify constraints on the size of the value. See the documentation for each WS_TYPE for how these constraints are specified.

Remarks

Each WS_READ_OPTION discusses when a WS_HEAP object must be specified. Depending on the function, it may still be possible to pass a NULL heap parameter in this case; see the documentation for the specific function for details on whether a default heap is used if the heap parameter is NULL.

The following are things to consider when deserializing values into a heap object (WS_HEAP):

  • Deserialized values remain allocated until the heap is freed (WsFreeHeap) or reset (WsResetHeap).
  • Each time values are deserialized, they are appended to the heap (instead of replacing existing values).
  • If errors are encountered during the deserialization function and the function fails, the memory allocated from the heap object up until the error will not be released.
  • The size of the heap can be used to limit the total allocations made during deserialization. The max size of the heap can be determined in the following way:
    • Determine the max size, in bytes, of each value that will be allocated on the heap during deserialization. Remember to take into account that sizes of deserialized data structures may vary by platform.
    • Each array is considered one value. Note that the actual size of an item in the array may by affected by the required alignment of the item.
    • Round the max size of each value to a 16-byte boundary.

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

 

 

Community Additions

Show:
© 2015 Microsoft