MCD_STR CMarkup::GetResult();
Call GetResult to get a markup string with result and error details after a parser or file operation. The GetError method converts the result markup into an English readable string. To support application localization, use GetResult instead of GetError so that your output strings can be in your application resources. You can copy the GetError method source code as a starting point or use it as a guide for processing the results you need to display or output.
If you call Load with a filename that it does not find, the GetError method just returns this string:
The system cannot find the file specified.
The GetResult method returns markup which identifies it as a file_error and includes the errno or system error number.
<file_error msg="The system cannot find the file specified." n="2"/>
This code demonstrates how you can examine the result string returned by GetResult:
MCD_STR strFileErrorMsg;
CMarkup mResult( xml.GetResult() );
if ( mResult.FindElem(MCD_T("file_error")) )
strFileErrorMsg = mResult.GetAttrib( MCD_T("msg") );
These are the possible result tag names and associated attributes for the parser errors and file I/O results.
| result tag name | attributes | GetError returns |
|---|---|---|
| root_has_sibling | root element has sibling | |
| no_root_element | no root element | |
| unended_start_tag | tagname offset offset2 | start tag '@tagname' at offset @offset expecting end tag at offset @offset2 |
| first_tag_syntax | offset | tag syntax error at offset @offset expecting tag name / ! or ? |
| exclamation_tag_syntax | offset | tag syntax error at offset @offset expecting 'DOCTYPE' [ or - |
| doctype_tag_syntax | offset | tag syntax error at offset @offset expecting markup declaration (ELEMENT ATTLIST ENTITY NOTATION) |
| comment_tag_syntax | offset | tag syntax error at offset @offset expecting - to begin comment |
| cdata_section_syntax | offset | tag syntax error at offset @offset expecting 'CDATA' |
| unterminated_tag_syntax | type offset | unterminated tag at offset @offset (document type, element start tag, element end tag, CDATA section, processing instruction, comment) |
| file_error | msg n | @msg |
| read | encoding length | @encoding length @length |
| write | encoding length | @encoding length @length |
| converted_to | encoding length | to @encoding length @length |
| converted_from | encoding length | @encoding length @length to |
| bom | BOM + | |
| nulls_removed | count | removed @count nulls |
| conversion_loss | (chars lost in conversion!) | |
| utf8_detection | (used UTF-8 detection) | |
| endian_swap | endian swap | |
| truncation_error | encoding | error truncating @encoding |
On a read operation (Load, ReadTextFile, or file read mode), there will be a read element telling the encoding in the file and the length. The bom element notifies you that the file had a UTF-16 BOM or UTF-8 preamble (corresponding to the encoding of the file).
xml.SetDocFlags( xml.MDF_UTF8PREAMBLE );
xml.Save( MCD_T_FILENAME("test.xml") );
GetError returns "BOM + UTF-8 length 35", and GetResult returns:
<bom/><read encoding="UTF-8" length="35"/>
Next is an example of loading a UTF-16 file in a program that uses UTF-8 strings in memory. GetError returns "BOM + UTF-16LE length 34 to UTF-8 length 35". In the result, the additional conversion information is in a converted_to element.
<bom/><read encoding="UTF-16LE" length="34"/><converted_to encoding="UTF-8" length="35"/>
Here is some code to process the result.
CMarkup mResult( xml.GetResult() );
mResult.FindElem( MCD_T("bom") );
mResult.FindElem( MCD_T("read") );
mResult.GetAttrib( MCD_T("encoding") ); // "UTF-16LE"
mResult.FindElem( MCD_T("converted_to") );
mResult.GetAttrib( MCD_T("encoding") ); // "UTF-8"
The following code saves an empty document in UTF-16BE.
CMarkup xml;
xml.SetDocFlags( xml.MDF_UTF16BEFILE );
xml.Save( MCD_T_FILENAME("test.xml") );
GetError returns "BOM + UTF-16BE length 0", and GetResult returns a write element:
<bom/><write encoding="UTF-16BE" length="0"/>
If a conversion is involved, the write element is preceeded by a converted_from element. In the next example, GetError returns UTF-8 length 131092 to GB18030 length 90132".
<converted_from encoding="UTF-8" length="131092"/><write encoding="GB18030" length="90132"/>
See also: