CMarkup GetResult Method

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.

File Error

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") );

List of error codes

These are the possible result tag names and associated attributes for the parser errors and file I/O results.

result tag nameattributesGetError returns
root_has_sibling root element has sibling
no_root_element no root element
unended_start_tagtagname offset offset2start tag '@tagname' at offset @offset expecting end tag at offset @offset2
first_tag_syntaxoffsettag syntax error at offset @offset expecting tag name / ! or ?
exclamation_tag_syntaxoffsettag syntax error at offset @offset expecting 'DOCTYPE' [ or -
doctype_tag_syntaxoffsettag syntax error at offset @offset expecting markup declaration (ELEMENT ATTLIST ENTITY NOTATION)
comment_tag_syntaxoffsettag syntax error at offset @offset expecting - to begin comment
cdata_section_syntaxoffsettag syntax error at offset @offset expecting 'CDATA'
unterminated_tag_syntaxtype offsetunterminated tag at offset @offset (document type, element start tag, element end tag, CDATA section, processing instruction, comment)
file_errormsg n@msg
readencoding length@encoding length @length
writeencoding length@encoding length @length
converted_toencoding lengthto @encoding length @length
converted_fromencoding length@encoding length @length to
bom BOM +
nulls_removedcountremoved @count nulls
conversion_loss (chars lost in conversion!)
utf8_detection (used UTF-8 detection)
endian_swap endian swap
truncation_errorencodingerror truncating @encoding

Read examples

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"

Write examples

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:

When CMarkup Load Returns false