You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

ParsingEBMLStreams.dox 4.4KB

3 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129
  1. /**
  2. * \page Doc_ParsingEBMLStreams Parsing EBML streams
  3. *
  4. * \section Doc_ParsingEBMLStreams_Introduction Introduction
  5. *
  6. * This page tries to teach how a user of this library should use
  7. * the reading functions in order to read and parse an EBML
  8. * stream correctly. For those who don't know what EBML is,
  9. * it is basically a binary XML created and used by the matroska
  10. * developpers. The libmatroska is based on the libebml
  11. * implementation of these guys. Fore more details, please read
  12. * the \ref Doc_WhatIsEBML page first and eventually visit the
  13. * EBML web page at http://ebml.sourceforge.net/
  14. *
  15. * \section Doc_ParsingEBMLStreams_Concept Concepts
  16. *
  17. * The idea of this parsing library is to transform the stream
  18. * data provided by the user application into understandable
  19. * EBML interpreted commands. Once the EBML nodes are found and
  20. * parsed, they are sent to a callback object that should know
  21. * what to do with them.
  22. *
  23. * The design of the parsing interface is closed to the one of
  24. * \c eXpat, an XML parser library (see http://expat.sourceforge.net
  25. * for more details on \c eXpat). Using such interface allows light
  26. * code and on-the-fly parsing, that means the parser does not
  27. * need to have all the data ready before starting the parsing
  28. * process... The data can arrive while the parsing is beeing
  29. * done.
  30. *
  31. * It is the responsability of the user application to read
  32. * the EBML stream from a file, a socket, a user input or
  33. * whatever, and then to send this to the parser...
  34. *
  35. * At least, the callback object may use a reader helper that
  36. * knows how to read standard EBML types such as integers,
  37. * floats, strings etc...
  38. *
  39. * The library is divided into three main components :
  40. * - The reader itself that does the parsing stuffs
  41. * - An implementation of the callback object (the implementation
  42. * is left to the user application developper)
  43. * - An optionnal helper object that knows more on the
  44. * content of the EBML stream.
  45. *
  46. * Here comes the organisation of the different modules and how
  47. * data go from one to another. Note that the user application
  48. * and the user callback object may share some information so the
  49. * callback object communicates with the application itself.
  50. *
  51. * \image html ebml_parsing_concept.png "Concept"
  52. *
  53. * Here comes the UML class diagram, presenting the main classes
  54. * involved in the presented behavior.
  55. *
  56. * \image html ebml_parsing_class.png "Class Diagram"
  57. *
  58. * See EBML::IReader, EBML::IReaderCallback and EBML::IReaderHelper
  59. * for more details on each of these classes.
  60. *
  61. * \section Doc_ParsingEBMLStreams_SampleCode Sample code
  62. *
  63. * In this section, a sample of user application code is presented
  64. * that parses the sample file created in the page named :
  65. * \ref Doc_FormatingEBMLStreams
  66. *
  67. * The parsed value are printed in the console.
  68. *
  69. * The callback object looks something like this :
  70. *
  71. * \code
  72. * class CReaderCallback : public EBML::IReaderCallback
  73. * {
  74. * public:
  75. * CReaderCallback()
  76. * {
  77. * m_helper=EBML::createReaderHelper();
  78. * }
  79. * virtual ~CReaderCallback()
  80. * {
  81. * if(m_helper) m_helper->release();
  82. * }
  83. * virtual bool isMasterChild(const EBML::CIdentifier& identifier)
  84. * {
  85. * if(identifier==EBML_Identifier_Header) return true;
  86. * if(identifier==EBML_Identifier_DocType) return true;
  87. * if(identifier==EBML_Identifier_DocTypeVersion) return true;
  88. * return false;
  89. * }
  90. * virtual void openChild(const EBML::CIdentifier& identifier)
  91. * {
  92. * m_oCurrent=identifier;
  93. * }
  94. * virtual void processChildData(const void* buffer, const size_t size)
  95. * {
  96. * if(m_oCurrent==EBML_Identifier_DocType)
  97. * std::cout << "Doc type:" << m_helper->getStr(buffer, size) << std::endl;
  98. * if(m_oCurrent==EBML_Identifier_DocTypeVersion)
  99. * std::cout << "Dox type version:" << m_helper->getUInt(buffer, size) << std::endl;
  100. * }
  101. * virtual void closeChild()
  102. * {
  103. * }
  104. * EBML::IReaderHelper* m_helper;
  105. * };
  106. * \endcode
  107. *
  108. * Then in the user application code, we can write the
  109. * initialisation this way :
  110. *
  111. * \code
  112. * CReaderCallback oCallback;
  113. * EBML::IReader* pReader=EBML::createReader(oCallback);
  114. * \endcode
  115. *
  116. * Now suppose the user application got some data from the file
  117. * in a \c buffer of size \c size ; it is sent to the
  118. * parser this way :
  119. *
  120. * \code
  121. * pReader->processData(buffer, size);
  122. * \endcode
  123. *
  124. * Finally, don't forget to release the object and to clean memory :
  125. *
  126. * \code
  127. * pReader->release();
  128. * \endcode
  129. */