WsReadToStartElement 函数 (webservices.h)

  • 项目

如有必要，将读取器推进到下一个 start 元素，跳过空格和注释。 （可选）它还可以验证元素的 localName 和命名空间。

语法

HRESULT WsReadToStartElement(
  [in]           WS_XML_READER       *reader,
  [in, optional] const WS_XML_STRING *localName,
  [in, optional] const WS_XML_STRING *ns,
                 BOOL                *found,
  [in, optional] WS_ERROR            *error
);

参数

[in] reader

要读取到 start 元素的读取器。

[in, optional] localName

元素应为的 localName 名称。 如果 为 NULL，则允许任何 localName。

[in, optional] ns

元素应为的命名空间。 如果 为 NULL，则允许任何命名空间。

found

如果指定了 ，则会指示是否找到元素，并且 localName 和命名空间（如果还指定）匹配。 如果未指定，并且找不到元素，或者 localName 和命名空间不匹配，则它将返回 WS_E_INVALID_FORMAT。 (请参阅 Windows Web Services 返回值。)

[in, optional] error

指定在函数失败时应存储其他错误信息的位置。

返回值

此函数可以返回其中一个值。

返回代码 说明
WS_E_INVALID_FORMAT
 输入数据的格式不是预期的，或者没有预期的值。
WS_E_QUOTA_EXCEEDED
 超出配额。

注解

请考虑以下 XML：

<!-- A purchase order -->
        <PurchaseOrder xmlns='http://tempuri.org'>
            <Item>
                Pencil
            </Item>
        </PurchaseOrder>

以下示例演示了当读者位于文档的不同位置时 WsReadToStartElement 的行为。

WS_XML_STRING purchaseOrder = WS_XML_STRING_VALUE("PurchaseOrder");
WS_XML_STRING item = WS_XML_STRING_VALUE("Item");
WS_XML_STRING ns = WS_XML_STRING("http://tempuri.org");
WS_ERROR* error = NULL;

// Example 1: Reader on comment, element has specified name and namespace, found argument is not provided
HRESULT hr = WsReadToStartElement(reader, &purchaseOrder, &ns, NULL, error);
// hr = NOERROR, the reader is positioned on <PurchaseOrder>

// Example 2: Reader on comment, element has specified name and namespace, found argument is provided
BOOL found;
HRESULT hr = WsReadToStartElement(reader, &purchaseOrder, &ns, found, error);
// hr = NOERROR, found = TRUE, the reader is positioned on <PurchaseOrder>

// Example 3: Reader on comment, element does not have specified name and namespace, found argument is not provided
HRESULT hr = WsReadToStartElement(reader, &item, &ns, NULL, error);
// hr = WS_E_INVALID_FORMAT, the reader is faulted

// Example 4: Reader on comment, element does not have specified name and namespace, found argument is provided
BOOL found;
HRESULT hr = WsReadToStartElement(reader, &item, &ns, &found, error);
// hr = NOERROR, found = FALSE, the reader is positioned on <PurchaseOrder>

// Example 5: Reader on comment, name and namespace not specified, found argument is provided
BOOL found;
HRESULT hr = WsReadToStartElement(reader, NULL, NULL, &found, error);
// hr = NOERROR, found = TRUE, the reader is positioned on <PurchaseOrder>

// Example 6: Reader on </Item>, name and namespace not specified, found argument is not provided
HRESULT hr = WsReadToStartElement(reader, NULL, NULL, NULL, error);
// hr = WS_E_INVALID_FORMAT, the reader is faulted

// Example 7: Reader on </Item>, name and namespace not specified, found argument is provided
BOOL found;
HRESULT hr = WsReadToStartElement(reader, NULL, NULL, &found, error);
// hr = NOERROR, found = FALSE, the reader is positioned on </Item>

如果 WsReadToStartElement 指示已找到元素，则 WsReadStartElement 或 WsReadNode 可用于将读取器从 start 元素移动到元素的内容中。

WsSkipNode 可用于跳过元素及其所有子元素，使读取器位于 WS_XML_NODE 相应的结束元素之后。

此函数可能由于 WsReadNode 中列出的任何原因而失败。

要求

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