spxmlhandle.hpp

00001 /*
00002  * Copyright 2008 Stephen Liu
00003  * LGPL, see http://code.google.com/p/spxml/
00004  * For license terms, see the file COPYING along with this library.
00005  */
00006 
00007 #ifndef __spxmlhandle_hpp__
00008 #define __spxmlhandle_hpp__
00009 
00010 class SP_XmlNode;
00011 
00012 class SP_XmlElementNode;
00013 class SP_XmlCDataNode;
00014 class SP_XmlCommentNode;
00015 
00016 /**
00017  *  This class is a clone of TinyXML's TiXmlHandle class.
00018  *
00019  *
00020  *  A SP_XmlHandle is a class that wraps a node pointer with null checks; this is
00021  *  an incredibly useful thing. Note that SP_XmlHandle is not part of the SPXml
00022  *  DOM structure. It is a separate utility class.
00023  *
00024 
00025     Take an example:
00026     @verbatim
00027     <Document>
00028         <Element attributeA = "valueA">
00029             <Child attributeB = "value1" />
00030             <Child attributeB = "value2" />
00031         </Element>
00032     <Document>
00033     @endverbatim
00034 
00035     Assuming you want the value of "attributeB" in the 2nd "Child" element, a
00036     SP_XmlHandle checks for null pointers so it is perfectly safe and correct to use:
00037 
00038     @verbatim
00039     SP_XmlHandle rootHandle( parser.getDocument()->getRootElement() );
00040     SP_XmlElementNode * child2 = rootHandle.getChild( "Element" )
00041             .getChild( "Child", 1 ).toElement();
00042 
00043     if( child2 ) {
00044         // do something
00045     }
00046     @endverbatim
00047  *
00048  */
00049 
00050 class SP_XmlHandle {
00051 public:
00052     SP_XmlHandle( SP_XmlNode * node );
00053     SP_XmlHandle( const SP_XmlHandle & ref );
00054     SP_XmlHandle & operator=( const SP_XmlHandle & ref );
00055 
00056     ~SP_XmlHandle();
00057 
00058     SP_XmlHandle getChild( const char * name, int index = 0 ) const;
00059 
00060     SP_XmlHandle getChild( int index ) const;
00061 
00062     SP_XmlHandle getElement( int index ) const;
00063 
00064     SP_XmlNode * toNode();
00065 
00066     SP_XmlElementNode * toElement();
00067 
00068     SP_XmlCDataNode * toCData();
00069 
00070 private:
00071     SP_XmlNode * mNode;
00072 };
00073 
00074 #endif
00075