WsReadToStartElement 函式 (webservices.h)

視需要將讀取器移至下一個開始元素，略過空格符和批注。 您也可以選擇性地驗證專案的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 服務傳回值。)

[in, optional] error

指定函式失敗時應該儲存其他錯誤資訊的位置。

傳回值

此函式可以傳回其中一個值。

備註

請考慮下列 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 可用來將讀取器移出開始元素的內容。

WsSkipNode 可用來略過專案及其所有子系，讓讀取器位於對應的 end 元素之後 WS_XML_NODE 。

此函式可能會因為 WsReadNode 中列出的任何原因而失敗。

規格需求