WS_READ_OPTION 枚举 (webservices.h)

  • 项目

指定是否需要值，以及如何分配该值。

语法

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;

常量

 
WS_READ_REQUIRED_VALUE
值：1
选项指定值必须存在于 XML 内容中。


调用方必须指定要将顶级类型读取到的存储。


调用方指定的存储大小因类型而异
被反序列化，如下所示：

  • 对于基元 (（如 WS_INT32_TYPE) ），存储应
    是基元的大小。 在这种情况下，不需要指定堆。

  • 对于结构 (是否使用 WS_STRUCT_TYPE的用户定义结构，
    或预定义的，如 WS_STRING) ，存储应为
    结构的确切大小。
    请注意，仍需要指向其他数据的结构的字段
    从 WS_HEAP分配。 如果 不存在
    特定结构，则不需要指定堆。




指针类型 (WS_WSZ_TYPE 和 WS_XML_BUFFER_TYPE) ，
不能与 WS_READ_REQUIRED_VALUE一起使用。 WS_READ_REQUIRED_POINTER
应改用 value。


如果正在读取的 XML 中不存在该值，
将返回 WS_E_INVALID_FORMAT 错误。
(请参阅 Windows Web Services 返回值。)
WS_READ_REQUIRED_POINTER
值： 2
选项指定值必须存在于 XML 内容中。


反序列化值始终在 WS_HEAP上分配，无论其大小如何。
返回指向反序列化值的指针。 使用此选项时，
调用方应传递指针的地址和指针的大小，
无论反序列化的类型如何。


如果该值不存在，则将返回错误。
使用此选项时，永远不会返回 NULL。 如果你的设备不支持
值是可选的，请使用 WS_READ_OPTIONAL_POINTER。
WS_READ_OPTIONAL_POINTER
值： 3
选项指定值不需要存在于 XML 内容中。


反序列化值始终在 WS_HEAP上分配，无论其大小如何。
返回指向反序列化值的指针。 使用此选项时，
调用方应传递指针的地址和指针的大小，
无论反序列化的类型如何。


如果正在读取的 XML 中不存在该值，则函数将
成功，将为值返回 NULL 。


使用此选项的应用程序在访问该值之前，应小心检查 NULL。
如果永远不需要 NULL 值，请使用 WS_READ_REQUIRED_POINTER。
WS_READ_NILLABLE_POINTER
值： 4
选项指定该值在 XML 内容中可能为零或缺失。


反序列化值始终在 WS_HEAP上分配，无论其大小如何。
返回指向反序列化值的指针。 使用此选项时，
调用方应传递指针的地址和指针的大小，
无论反序列化的类型如何。


如果正在读取的 XML 中元素为零或缺失，则函数将成功，并且
将返回 NULL 指针。
如果正在读取的 XML 中元素不为 nil，则正常返回该值。


使用此选项的应用程序在访问该值之前，应小心检查 NULL。
如果永远不需要 NULL 值，请使用 WS_READ_REQUIRED_POINTER。


不支持将此选项与 API 中的 WS_TYPE_MAPPING 结合使用
读取 XML 的 ，包括 WsReadType 和 WsReadElement 调用。
WS_READ_NILLABLE_VALUE
值： 5
选项指定该值在 XML 内容中可能为零或缺失。


调用方必须指定要将顶级类型读取到的存储。


如果 XML 元素为 nil 或缺失，则返回 nil 值。 如果 XML 元素为
非 nil，则值正常反序列化。


不支持将此选项与 API 中的 WS_TYPE_MAPPING 结合使用
读取 XML 的 ，包括 WsReadType 和 WsReadElement 调用。


此选项仅支持以下类型，如下所示：
具有表示零值的内部方式。 请参阅文档
，了解 nil 的表示方式。

注解

每个 WS_READ_OPTION 讨论何时必须指定 WS_HEAP 对象。 在这种情况下，可能仍可以传递 NULL 堆参数，具体取决于函数;有关在堆参数为 NULL 时是否使用默认堆的详细信息，请参阅特定函数的文档。

将值反序列化为堆对象 (WS_HEAP) 时，需要考虑以下事项：

  • 在释放堆 (WsFreeHeap) 或重置 (WsResetHeap) 之前，反序列化值将保持分配状态。
  • 每次反序列化值时，它们都会追加到堆 (，而不是) 替换现有值。
  • 如果在反序列化函数期间遇到错误，并且该函数失败，则不会释放从堆对象分配的内存，直到错误为止。
  • 堆的大小可用于限制反序列化期间进行的总分配。 堆的最大大小可按以下方式确定：
    • 确定反序列化期间将在堆上分配的每个值的最大大小（以字节为单位）。 请记住，反序列化数据结构的大小可能因平台而异。
    • 每个数组被视为一个值。 请注意，数组中项的实际大小可能受该项所需对齐方式的影响。
    • 将每个值的最大大小舍入为 16 字节边界。

要求

要求 值
最低受支持的客户端 Windows 7 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2008 R2 [桌面应用 |UWP 应用]
标头 webservices.h