From da875b083ce3f28e4463497873e2bc604e5767a9 Mon Sep 17 00:00:00 2001
From: Mathias Laurenz Baumann <marenz@nebel.localdomain>
Date: Sun, 31 Jan 2010 15:27:00 +0100
Subject: [PATCH] inital commit with suggested api from the wiki

---
 include/psyc.h | 129 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 include/psyc.h

diff --git a/include/psyc.h b/include/psyc.h
new file mode 100644
index 0000000..7baf689
--- /dev/null
+++ b/include/psyc.h
@@ -0,0 +1,129 @@
+/** @brief parses a packet
+ *
+ * This function parses rawdata
+ * and uses the callbacks in PSYC_Parser
+ * to communicate with the caller.
+ *
+ * First the header will be parsed,
+ * after that the stateCallback
+ * (with inEntity set to false)
+ * will be called for each variable.
+ * Then, routingCallback will be called
+ * to find out if further parsing
+ * is desired.
+ * If it returns false, PSYC_parser returns.
+ * If it returns true, parsing continues
+ * to the body.
+ * After the entitystate has been parsed,
+ * stateCallback will be called for each
+ * variable, having inEntity set to true.
+ * Finally, bodyCallback will be called,
+ * containing the method, and its data.
+ *
+ * In case of an parsing error <to continue>
+ *
+ * @param data constant pointer to the 
+ *        raw data that is to be processed.
+ * @param length the amount of bytes to parse
+ * @param pstate pointer to a preallocated 
+ *        instance of the struct state   
+*/
+void PSYC_parse(const uint8_t* data, unsigned int length, 
+                struct PSYC_Parser* pstate);
+
+/** @brief FlagMod */
+enum PSYC_Modifier
+{ 
+	// variable modifers
+	ASSIGN=0x02, 
+	AUGMENT=0x04, 
+	DIMINISH=0x08, 
+	SET=0x10, 
+	QUERY=0x20 
+}
+
+
+struct PSYC_Parser
+{     
+	/** @brief Callback for the states
+	 *
+	 * This callback will be called to inform
+	 * the caller about the states.
+	 *
+	 * It will be called once for each variable.
+	 *
+	 * @param pstate pointer to the ParserState 
+	 *        struct for identification
+	 * @param name not null terminated c-string, 
+	 *        containing the name of the variable
+	 * @param nlength the length of the variable name
+	 * @param value not null terminated c-string,
+	 *        containing the value of the variable
+	 * @param vlength the length of the variable value
+	 * @param modifers modifer of the variable (see Modifer)
+	 * @param inEntity wether this variable is an entity 
+	 *        variable(true) or a routing variable(false) */
+	void (*stateCallback)(PSYC_Parser* pstate,
+	       const uint8_t *name, const unsigned int nlength,
+	       const uint8_t *value, const unsigned int vlength;
+	       PSYC_Modifer modifiers, bool inEntity);
+
+	/** @brief gets called after the routing-header was parsed
+	 *
+	 * @return if true, parser will continue to parse 
+	 *         the content part and calls bodyCallback 
+	 *         when finished, 
+	 *         if false, parser will stop parsing and 
+	 *         calls contentCallback */
+	bool (*routingCallback)(PSYC_Parser* pstate);
+
+	/** @brief Body callback, gets called when the body was parsed
+	 * 
+	 * @param pstate pointer to the ParserState struct
+	 *        for identificiation
+	 * @param method not null terminated c-string, 
+	 *        containing the method name
+	 * @param mlength the length of the methodname
+	 * @param dlength the length of the data
+	 * @param data not null terminated c-string,
+	 *        containing the data section
+	 * @param content not null terminated c-string
+	 * @param clength length of the content string */
+	void (*bodyCallback)(PSYC_Parser* pstate,
+	                 const uint8_t* method, unsigned int mlength,
+	                 const uint8_t* data, unsigned int dlength   
+	                 const uint8_t* content, unsigned int clength);
+
+	/** @brief Error callback, gets called to indicate 
+	 *         an error and the start of an error packet
+	 *          
+	 * If there was an error while parsing the rawdata,
+	 * instead of passing the packets data to the callbacks,
+	 * an error packet will be passed back, describing the 
+	 * the error in more detail.
+	 * 
+	 * On error, errorCallback will be called 
+	 * to report the errortype (in the method),
+	 * after that errorStateCallback will be 
+	 * called to inform about more detailed facts
+	 * of the error. 
+	 *
+	 * Any previous state or body callbacks become 
+	 * invalid and have to be purged.*/
+	void (*errorCallback)(PSYC_Parser* pstate, 
+	                 const uint8_t *method, unsigned int mlength);
+
+	/** @brief error state callback
+	 *
+	 * The parameters are the same as for stateCallback.
+	 * The callback will be called once for each
+	 * state variable in the error report packet
+	 */
+	void (*errorStateCallback)(PSYC_Parser* pstate,
+	       const uint8_t *name, const unsigned int nlength,
+	       const uint8_t *value, const unsigned int vlength;
+	       PSYC_Modifer modifiers);
+	
+}
+
+