From b8ea04e415d584803a240e9e18d24c895052f4b0 Mon Sep 17 00:00:00 2001
From: deva <deva>
Date: Wed, 29 Jul 2009 15:04:13 +0000
Subject: Added testscripts for SAXParser. Added SAXParser documentation.

---
 server/src/saxparser.h | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)

(limited to 'server/src/saxparser.h')

diff --git a/server/src/saxparser.h b/server/src/saxparser.h
index da33440..9f2faa2 100644
--- a/server/src/saxparser.h
+++ b/server/src/saxparser.h
@@ -31,21 +31,92 @@
 #include <map>
 #include <expat.h>
 
+/**
+ * This class implements a SAX Parser, utilising the eXpat XML parser library.
+ * It uses virtual methods for the callbacks, and transforms tagnames and
+ * attributes into C++ values (std::string and std::vector).
+ */
 class SAXParser {
 public:
+  /**
+   * Constructor.
+   * It initialises the eXpat library.
+   */
   SAXParser();
+
+  /**
+   * Destructor.
+   * It frees the eXpat library resources.
+   */
   virtual ~SAXParser();
 
+  /**
+   * Call this method to use the reimplemented readData method for input.
+   * The entire document is parsed through this single call.
+   * @return An integer wityh value 0 on success, or 1 on failure.
+   * @see int readData(char *data, size_t size)
+   */
   int parse();
 
+  /**
+   * Character data callback method.
+   * Reimplement this to get character callbacks.
+   * This callback might be called several times, if a character block is big. In
+   * that cae it might be nessecary to buffer to received bytes.
+   * @param data A std::string containing the character data.
+   */
   virtual void characterData(std::string &data) {}
+
+  /**
+   * Start tag callback mehtod.
+   * Reimplement this to get start tag callbacks.
+   * It is called each time a new start tag is seen.
+   * @param name A std::string containing the tag name.
+   * @param attributes A std::map of std::string to std::string containing all
+   * attributes for the tag.
+   */
   virtual void startTag(std::string name, std::map< std::string, std::string> attributes) {}
+
+  /**
+   * End tag callback mehtod.
+   * Reimplement this to get end tag callbacks.
+   * It is called each time an end tag is seen.
+   * @param name A std::string containing the tag name.
+   */
   virtual void endTag(std::string name) {}
 
+  /**
+   * Error callback method.
+   * Reimplement this to handle error messages.
+   * A default implementation prints out the current buffer, linenumber and error
+   * message to the screen.
+   * @param buf A char* containing the current buffer being parsed.
+   * @param len A size_t containing the length of the current buffer being parsed.
+   * @param error A std::string containing the error message.
+   * @param lineno An integer containing the line number on which the error occurred.
+   */
   virtual void parseError(char *buf, size_t len, std::string error, int lineno);
 
+  /**
+   * Buffer parse method.
+   * Use this method to parse an external buffer with xml data.
+   * This method can be called several times (ie. in a read loop).
+   * @param buf A char* containing the buffer to parse.
+   * @param size A size_t comntaining the size of the buffer to parse.
+   * @return A boolean with the value true if a complete document has been seen.
+   * false otherwise.
+   * @see bool parse(char *buf, size_t size)
+   */
   bool parse(char *buf, size_t size);
 
+  /**
+   * Get the number of bytes used from the last buffer.
+   * If the buffer parse method is used, and the buffer comes from a stream of xml
+   * doxuments, this method can be used to figure out how many bytes from the stream
+   * should be replayed, to another parser.
+   * @return an integer containing the number of bytes used from the last buffer.
+   * @see bool parse(char *buf, size_t size)
+   */
   unsigned int usedBytes();
 
   // private stuff that needs to be public!
@@ -53,6 +124,17 @@ public:
   bool done;
 
 protected:
+  /**
+   * Read data callback method.
+   * This method is used when the parse() method is used.
+   * It can be used to connect the parser with eg. a file.
+   * @param data A char* containing the buffer to be filled.
+   * @param size A size_t containing the maximum number of bytes to be filled (ie.
+   * the size of data)
+   * @return An integer contaning the actual number of bytes filled. 0 if no more
+   * bytes are available.
+   * @see int parse()
+   */ 
   virtual int readData(char *data, size_t size) { return 0; }
 
   XML_Parser p;
-- 
cgit v1.2.3