init

2021-10-14 13:47:35 +02:00
commit 6625a8dfaa
4026 changed files with 844291 additions and 0 deletions
@@ -0,0 +1,95 @@
+/**
+ * \page Doc_FormatingEBMLStreams Formating EBML streams
+ *
+ * \section Doc_FormatingEBMLStreams_Introduction Introduction
+ *
+ * This page tries to teach how a user of this library should use
+ * the writing functions in order to build and format an EBML
+ * stream correctly. For those who don't know what EBML is,
+ * it is basically a binary XML created and used by the matroska
+ * developpers. The libmatroska is based on the libebml
+ * implementation of these guys. Fore more details, please read 
+ * the \ref Doc_WhatIsEBML page first and eventually visit the 
+ * EBML web page at http://ebml.sourceforge.net/
+ *
+ * \section Doc_FormatingEBMLStreams_Concept Concepts
+ *
+ * The idea of this formating library is to transform the data
+ * provided by the user application into EBML buffers. Those EBML
+ * buffers are then given to a user callback object which know
+ * what to do with the computed data (maybe write it to a file,
+ * send it on a socket, log it in a console, whatever...)
+ *
+ * The library is divided into three main components :
+ *  - The writer itself that does the formating stuff
+ *  - An implementation of the callback object (the implementation
+ *    is left to the user application developper)
+ *  - An optionnal helper object that knows more on the
+ *    content of the EBML stream.
+ *
+ * Here comes the organisation of the different modules and how
+ * data go from one to another. Note that the user application
+ * and the user callback object may share some information so the
+ * callback object communicates with the application itself.
+ *
+ * \image html ebml_formating_concept.png "Concept"
+ *
+ * Here comes the UML class diagram, presenting the main classes
+ * involved in the presented behavior.
+ *
+ * \image html ebml_formating_class.png "Class Diagram"
+ *
+ * See EBML::IWriter, EBML::IWriterCallback and EBML::IWriterHelper
+ * for more details on each of these classes.
+ *
+ * \section Doc_FormatingEBMLStreams_SampleCode Sample code
+ *
+ * In this section, a sample of user application code is presented
+ * that opens several child nodes and dumps the created stream
+ * into a file for later use. This file can be parsed using
+ * the sample code of the page named \ref Doc_ParsingEBMLStreams
+ *
+ * The callback object implementation looks something like this :
+ *
+ * \code
+ * class CWriterCallback : public EBML::IWriterCallback
+ * {
+ * public:
+ *   CWriterCallback(char* filename) { m_file=fopen(filename, "wb"); }
+ *   virtual ~CWriterCallback() { if(m_file) fclose(m_file); }
+ *   virtual void write(const void* buffer, const size_t size) { if(m_file) fwrite(buffer, size, 1, m_file); }
+ *   FILE* m_file;
+ * };
+ * \endcode
+ *
+ * Then in the user application code, we can write the
+ * initialisation this way :
+ *
+ * \code
+ * CWriterCallback oCallback("test.ebml");
+ * EBML::IWriter* pWriter=EBML::createWriter(oCallback);
+ * EBML::IWriterHelper* pWriterHelper=EBML::createWriterHelper();
+ * pWriterHelper->connect(pWriter);
+ * \endcode
+ *
+ * The use of the EBML writer looks something like this :
+ *
+ * \code
+ * pWriterHelper->openChild(EBML_Identifier_Header);
+ *   pWriterHelper->openChild(EBML_Identifier_DocType);
+ *     pWriterHelper->setStr("EBML basic sample");
+ *   pWriterHelper->closeChild();
+ *   pWriterHelper->openChild(EBML_Identifier_DocTypeVersion);
+ *     pWriterHelper->setUInt(1);
+ *   pWriterHelper->closeChild();
+ * pWriterHelper->closeChild();
+ * \endcode
+ *
+ * Finally, we have to release the objects and to clean memory :
+ *
+ * \code
+ * pWriterHelper->disconnect();
+ * pWriterHelper->release();
+ * pWriter->release();
+ * \endcode
+ */
@@ -0,0 +1,129 @@
+/**
+ * \page Doc_ParsingEBMLStreams Parsing EBML streams
+ *
+ * \section Doc_ParsingEBMLStreams_Introduction Introduction
+ *
+ * This page tries to teach how a user of this library should use
+ * the reading functions in order to read and parse an EBML
+ * stream correctly. For those who don't know what EBML is,
+ * it is basically a binary XML created and used by the matroska
+ * developpers. The libmatroska is based on the libebml
+ * implementation of these guys. Fore more details, please read 
+ * the \ref Doc_WhatIsEBML page first and eventually visit the 
+ * EBML web page at http://ebml.sourceforge.net/
+ *
+ * \section Doc_ParsingEBMLStreams_Concept Concepts
+ *
+ * The idea of this parsing library is to transform the stream
+ * data provided by the user application into understandable
+ * EBML interpreted commands. Once the EBML nodes are found and
+ * parsed, they are sent to a callback object that should know
+ * what to do with them.
+ *
+ * The design of the parsing interface is closed to the one of
+ * \c eXpat, an XML parser library (see http://expat.sourceforge.net
+ * for more details on \c eXpat). Using such interface allows light
+ * code and on-the-fly parsing, that means the parser does not
+ * need to have all the data ready before starting the parsing
+ * process... The data can arrive while the parsing is beeing
+ * done.
+ *
+ * It is the responsability of the user application to read
+ * the EBML stream from a file, a socket, a user input or
+ * whatever, and then to send this to the parser...
+ *
+ * At least, the callback object may use a reader helper that
+ * knows how to read standard EBML types such as integers,
+ * floats, strings etc...
+ *
+ * The library is divided into three main components :
+ *  - The reader itself that does the parsing stuffs
+ *  - An implementation of the callback object (the implementation
+ *    is left to the user application developper)
+ *  - An optionnal helper object that knows more on the
+ *    content of the EBML stream.
+ *
+ * Here comes the organisation of the different modules and how
+ * data go from one to another. Note that the user application
+ * and the user callback object may share some information so the
+ * callback object communicates with the application itself.
+ *
+ * \image html ebml_parsing_concept.png "Concept"
+ *
+ * Here comes the UML class diagram, presenting the main classes
+ * involved in the presented behavior.
+ *
+ * \image html ebml_parsing_class.png "Class Diagram"
+ *
+ * See EBML::IReader, EBML::IReaderCallback and EBML::IReaderHelper
+ * for more details on each of these classes.
+ *
+ * \section Doc_ParsingEBMLStreams_SampleCode Sample code
+ *
+ * In this section, a sample of user application code is presented
+ * that parses the sample file created in the page named :
+ * \ref Doc_FormatingEBMLStreams
+ *
+ * The parsed value are printed in the console.
+ *
+ * The callback object looks something like this :
+ *
+ * \code
+ * class CReaderCallback : public EBML::IReaderCallback
+ * {
+ * public:
+ *   CReaderCallback()
+ *   {
+ *     m_helper=EBML::createReaderHelper();
+ *   }
+ *   virtual ~CReaderCallback()
+ *   {
+ *     if(m_helper) m_helper->release();
+ *   }
+ *   virtual bool isMasterChild(const EBML::CIdentifier& identifier)
+ *   {
+ *     if(identifier==EBML_Identifier_Header) return true;
+ *     if(identifier==EBML_Identifier_DocType) return true;
+ *     if(identifier==EBML_Identifier_DocTypeVersion) return true;
+ *     return false;
+ *   }
+ *   virtual void openChild(const EBML::CIdentifier& identifier)
+ *   {
+ *     m_oCurrent=identifier;
+ *   }
+ *   virtual void processChildData(const void* buffer, const size_t size)
+ *   {
+ *     if(m_oCurrent==EBML_Identifier_DocType)
+ *       std::cout << "Doc type:" << m_helper->getStr(buffer, size) << std::endl;
+ *     if(m_oCurrent==EBML_Identifier_DocTypeVersion)
+ *       std::cout << "Dox type version:" << m_helper->getUInt(buffer, size) << std::endl;
+ *   }
+ *   virtual void closeChild()
+ *   {
+ *   }
+ *   EBML::IReaderHelper* m_helper;
+ * };
+ * \endcode
+ *
+ * Then in the user application code, we can write the
+ * initialisation this way :
+ *
+ * \code
+ * CReaderCallback oCallback;
+ * EBML::IReader* pReader=EBML::createReader(oCallback);
+ * \endcode
+ *
+ * Now suppose the user application got some data from the file
+ * in a \c buffer of size \c size ; it is sent to the
+ * parser this way :
+ *
+ * \code
+ * pReader->processData(buffer, size);
+ * \endcode
+ *
+ * Finally, don't forget to release the object and to clean memory :
+ *
+ * \code
+ * pReader->release();
+ * \endcode
+ */
@@ -0,0 +1,15 @@
+/**
+ * \page Doc_WhatIsEBML What is EBML
+ *
+ * This page tries to explain what EBML is and why it is usefull.
+ *
+ * - see http://ebml.sourceforge.net/ for more details
+ * - see http://ebml.sourceforge.net/specs/ for specifications
+ * - see http://www.matroska.org/technical/specs/ for even more details
+ *
+ * - check libebml for a sample implementation of EBML
+ * - check libmatroska for a sample of library using libebml
+ *   and a concrete use of EBML
+ *
+ * \todo Write more documentation on what EBML is
+ */