From: <oja...@us...> - 2007-03-01 21:18:21
|
Revision: 201 http://svn.sourceforge.net/gull/?rev=201&view=rev Author: ojacques Date: 2007-03-01 13:18:15 -0800 (Thu, 01 Mar 2007) Log Message: ----------- Some source documentation Modified Paths: -------------- seagull/trunk/src/generator-core/main.cpp seagull/trunk/src/library-parser-xml/parser.cpp seagull/trunk/src/protocol-binary/C_ProtocolBinary.cpp seagull/trunk/src/protocol-frame/C_ProtocolFrame.hpp Modified: seagull/trunk/src/generator-core/main.cpp =================================================================== --- seagull/trunk/src/generator-core/main.cpp 2007-03-01 20:22:27 UTC (rev 200) +++ seagull/trunk/src/generator-core/main.cpp 2007-03-01 21:18:15 UTC (rev 201) @@ -17,6 +17,98 @@ * */ +/** + * \mainpage Seagull code documentation + * Go back to user documentation: http://gull.sf.net/doc/ + * + * \section sec_intro Introduction + * The purpose of this documentation is to explain Seagull interns. + * It is a summary to help developers make their way through Seagull and + * start contributing. + * + * \section sec_modules Main modules + * - C_Generator: core of Seagull. Contains the main functions. + * - C_TrafficModel: internal model of Seagull to control the way new scenarios + * are created. + * - C_CallContext: Management of the call context + * - C_CallControl: Management of the calls. Pause, restart traffic, set call rate... + * - C_ReadControl: Takes care of reading the protocol events, keyboard events + * and associated scheduling. + * - generator-scenario: C_ScenarioControl provides methods relating to the + * execution of the scenario. C_Scenario takes care of reading and + * interpreting scenarios. + * - ProtocolData.cpp: definition of generic data types (string, number, + * number64, ...) used by Seagull, as well as associated operator overloads. + * - C_ProtocolFrame: virtual definition of a protocol and its messages. It + * contains the only objects that will be used by the generator + * - C_Transport: generic definition of a transport + * - C_CommandAction: Class from which derives all classes implementing an + * action. Start here if you want to add one. + * - C_DisplayObject: Class that displays various screens (statistics, help, + * traffic, ...) + * - + * + * \section sec_other_modules Other modules + * - common directory: contains all the .h files to adapt some system includes + * to the target compilation platform + * - C_DataLogRTDistrib: deals with response time logs (csv file) + * - exe-env directory: execution environment for each protocol + * - C_ExternalDataControl: manage external data files, to insert data into + * scenario messages during the call + * - generator-common: utils for the tool (buffer management, id, ...) + * - C_TransIP: IP v4 & v6 transport transport; daughter class of C_Transport + * - C_TransSCTP: SCTP transport library; daughter class of C_Transport + * - C_TransIPTLS: TLS transport; daughter class of C_TransIP + * - C_TransOCTcap32: OpenCall TCAP API transport; daughter class of C_Transport + * - C_ProtocolBinary: binary protocol definition (e.g. Diameter); daughter + * class of C_ProtocolBinaryFrame, C_MessageFrame + * - statistics: stats management + * - C_XmlData and C_XmlParser to parse the xml files (dictionary, scenario + * and configuration + * file) + * + * \section sec_threads Threads + * There are 5 threads in Seagull: + * + * - One thread that handles the whole traffic, + * - One thread for the keyboard, + * - One thread for the tool display, + * - One thread for the logs, + * - One thread for the statistics. + * They are handled in generator-core module + * + * \section sec_proto_msg Protocol and messages + * + * - To implement a text protocol, you need to create a new implementation of + * C_ProtocolFrame and C_MessageFrame like C_ProtocolBinary and C_MessageBinary + * - In those classes, you implement the management of the XML tags and the + * protocol definition + * - You need to add them in C_ProtocolControl to be instantiated by the tool + * + * \section sec_xmlparse XML parsing + * + * - Handled in module xml-parser + * - XML files are parsed by C_XmlParser + * - XML data are represented as a tree of elements (based on stl types): + * (<TAG (FIELD=\x93VALUE\x94)*> <\TAG>)* + * - Useful functions in C_XmlData allows to get the name of a tag, retrieve + * the value of a field or the list (stl) of element under one element. + * + * \section sec_channel Channel creation + * + * - C_TransIP (module library-trans-ip) implements the transport, based on + * virtual object C_Transport (module transport-frame) + * Done/Declared in conf file. + * - Channel = link between one protocol and one transport, with an open + * command for the transport + * + * \section sec_multichan Multi-channel policy + * + * - Automatic session based: possible to open several channels (using same + * or different protocols), but only the first channel used can be server. + * + */ + #include "Utils.hpp" #include "C_Generator.hpp" #include "GeneratorTrace.hpp" Modified: seagull/trunk/src/library-parser-xml/parser.cpp =================================================================== --- seagull/trunk/src/library-parser-xml/parser.cpp 2007-03-01 20:22:27 UTC (rev 200) +++ seagull/trunk/src/library-parser-xml/parser.cpp 2007-03-01 21:18:15 UTC (rev 201) @@ -23,6 +23,9 @@ #include "string_t.hpp" #include "Utils.hpp" +/** Method to parse XML like payload. + * + */ C_ProtocolFrame::T_MsgError parse_xml (char *P_buf, size_t *P_size, char *P_buf_header, Modified: seagull/trunk/src/protocol-binary/C_ProtocolBinary.cpp =================================================================== --- seagull/trunk/src/protocol-binary/C_ProtocolBinary.cpp 2007-03-01 20:22:27 UTC (rev 200) +++ seagull/trunk/src/protocol-binary/C_ProtocolBinary.cpp 2007-03-01 21:18:15 UTC (rev 201) @@ -4800,6 +4800,12 @@ return (L_msg); } +/** Encode a binary message + * \param P_msg points to the message the message to be coded + * \param P_buffer The destination buffer + * \param P_buffer_size The destination buffer size + * \return E_MSG_OK if OK + */ C_ProtocolFrame::T_MsgError C_ProtocolBinary::encode_message(C_MessageFrame *P_msg, unsigned char *P_buffer, Modified: seagull/trunk/src/protocol-frame/C_ProtocolFrame.hpp =================================================================== --- seagull/trunk/src/protocol-frame/C_ProtocolFrame.hpp 2007-03-01 20:22:27 UTC (rev 200) +++ seagull/trunk/src/protocol-frame/C_ProtocolFrame.hpp 2007-03-01 21:18:15 UTC (rev 201) @@ -43,40 +43,45 @@ } T_NameAndId, *T_pNameAndId ; typedef list_t<T_NameAndId> T_NameAndIdList, *T_pNameAndIdList ; - +/** + * Protocol frame class. + */ class C_ProtocolFrame { // Protocol Frame Definition Class public: - + /** Possible protocol types */ typedef enum _protocol_type { - E_PROTOCOL_BINARY, - E_PROTOCOL_EXTERNAL, - E_PROTOCOL_TEXT, - E_PROTOCOL_UNKNOWN + E_PROTOCOL_BINARY, /** Used by Diameter, Radius and the like */ + E_PROTOCOL_EXTERNAL, /** Used by OpenCall TCAP. Can be used for any external API */ + E_PROTOCOL_TEXT, /** Used by SIP, HTTP, XCAP, H248 ascii and any "Ascii" based protocol */ + E_PROTOCOL_UNKNOWN /** Unused */ } T_ProtocolType, *T_pProtocolType ; + /** Error message code */ typedef enum _msg_error_code { E_MSG_OK = 0, - E_MSG_ERROR_DECODING, - E_MSG_ERROR_DECODING_SIZE_LESS, - E_MSG_ERROR_ENCODING, - E_MSG_EXTERNAL_ERROR, // used for EXTERNAL protocol type - E_MSG_INTERNAL_ERROR // used for EXTERNAL protocol type + E_MSG_ERROR_DECODING, /** Not able to decode the message */ + E_MSG_ERROR_DECODING_SIZE_LESS, /** Need more data to decode the message. This is the case when a message is not received in one recv */ + E_MSG_ERROR_ENCODING, /** Not able to encode the message*/ + E_MSG_EXTERNAL_ERROR, /** used for EXTERNAL protocol type */ + E_MSG_INTERNAL_ERROR /** used for EXTERNAL protocol type */ } T_MsgError, *T_pMsgError ; C_ProtocolFrame() {m_type = E_PROTOCOL_UNKNOWN; m_name=NULL; m_stats = NULL;} ; virtual ~C_ProtocolFrame() {} ; + /** Return the type of the protocol */ T_ProtocolType get_type() { return (m_type); } - + /** Create a new message */ virtual C_MessageFrame* create_new_message (C_MessageFrame *P_msg) = 0 ; // void * for P_Xml parameter: // Xml internal format not exported for transport + /** Create a new message */ virtual C_MessageFrame* create_new_message (void *P_xml, T_pInstanceDataList P_list, int *P_nb_body_value) = 0 ; This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |