GetValue

Article
10/27/2016

Returns the value of the current token, if applicable.

Syntax

  
HRESULT GetValue ([out] const WCHAR ** ppwszValue, [out] UINT * pcwchValue);

Arguments

ppwszValue
The value of the token. The returned string is always NULL terminated.

The passed in value cannot be NULL.

pcwchValue
The size of the string, in characters, is returned.

This value is optional. You can pass NULL for it, and the method will not return a value.

Return Value

Returns S_OK if no error is generated. Returns E_PENDING if the value is unavailable, and the stream is paused.

Remarks

Returns the value of the current token, if applicable. This method does not process or interpret the value returned.

This method does not return to the start of a value that has already been partially read. In other words, if ReadValueChunk has already been called while the reader is positioned on this text node, GetValue will return only the part of the value that has not already been read.

This method returns an empty string if the reader is positioned on an element node.

When the reader is positioned on a processing instruction, this method returns the content of the processing instruction. For example, when the reader is positioned on the text node of the processing instruction <?xyz abc?>, GetValue returns the string "abc".

When the reader is positioned on the content of a document type declaration, GetValue returns the content of the internal Document Type Definition (DTD) that is referenced by the document type declaration.

Note

The pointer returned by GetValue is only valid until you move the reader to another node. When you move the reader to another node, XmlLite may reuse the memory referenced by the pointer. Therefore, you should not use the pointer after calling one of the following methods: Read, MoveToNextAttribute, MoveToFirstAttribute, MoveToAttributeByName, or MoveToElement. Although they do not move the reader, the following two methods will also make the pointer invalid: SetInput and IUnknown::Release. If you want to preserve the value that was returned in ppwszValue, you should make a deep copy.

Handling of the return value E_PENDING is handled by the calling method.

The following code gets the value of the current node of the reader:

// This is a sample of how one might handle E_PENDING  
if (PENDING(hr = pReader->GetValue(&pwszValue, NULL))){  
    // Alert user to the pending notification  
    wprintf(L"Error pending, error is %08.8lx", hr);  
  
        // As long as E_PENDING is returned keep trying to get value  
        while (PENDING(hr){  
            ::sleep(1000);  
            hr = pReader->GetValue(&pwszValue, NULL);  
        }  
        continue;  
    }  
if (FAILED(hr = pReader->GetValue(&pwszValue, NULL))){  
    wprintf(L"Error getting value, error is %08.8lx", hr);  
    return -1;  
}  
wprintf(L"Text: %s\n", pwszValue);

Requirements

Header: XmlLite.h

Library: XmlLite.lib

Share via