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.

FormatingEBMLStreams.dox 3.5KB

3 years ago
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495
  1. /**
  2. * \page Doc_FormatingEBMLStreams Formating EBML streams
  3. *
  4. * \section Doc_FormatingEBMLStreams_Introduction Introduction
  5. *
  6. * This page tries to teach how a user of this library should use
  7. * the writing functions in order to build and format 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_FormatingEBMLStreams_Concept Concepts
  16. *
  17. * The idea of this formating library is to transform the data
  18. * provided by the user application into EBML buffers. Those EBML
  19. * buffers are then given to a user callback object which know
  20. * what to do with the computed data (maybe write it to a file,
  21. * send it on a socket, log it in a console, whatever...)
  22. *
  23. * The library is divided into three main components :
  24. * - The writer itself that does the formating stuff
  25. * - An implementation of the callback object (the implementation
  26. * is left to the user application developper)
  27. * - An optionnal helper object that knows more on the
  28. * content of the EBML stream.
  29. *
  30. * Here comes the organisation of the different modules and how
  31. * data go from one to another. Note that the user application
  32. * and the user callback object may share some information so the
  33. * callback object communicates with the application itself.
  34. *
  35. * \image html ebml_formating_concept.png "Concept"
  36. *
  37. * Here comes the UML class diagram, presenting the main classes
  38. * involved in the presented behavior.
  39. *
  40. * \image html ebml_formating_class.png "Class Diagram"
  41. *
  42. * See EBML::IWriter, EBML::IWriterCallback and EBML::IWriterHelper
  43. * for more details on each of these classes.
  44. *
  45. * \section Doc_FormatingEBMLStreams_SampleCode Sample code
  46. *
  47. * In this section, a sample of user application code is presented
  48. * that opens several child nodes and dumps the created stream
  49. * into a file for later use. This file can be parsed using
  50. * the sample code of the page named \ref Doc_ParsingEBMLStreams
  51. *
  52. * The callback object implementation looks something like this :
  53. *
  54. * \code
  55. * class CWriterCallback : public EBML::IWriterCallback
  56. * {
  57. * public:
  58. * CWriterCallback(char* filename) { m_file=fopen(filename, "wb"); }
  59. * virtual ~CWriterCallback() { if(m_file) fclose(m_file); }
  60. * virtual void write(const void* buffer, const size_t size) { if(m_file) fwrite(buffer, size, 1, m_file); }
  61. * FILE* m_file;
  62. * };
  63. * \endcode
  64. *
  65. * Then in the user application code, we can write the
  66. * initialisation this way :
  67. *
  68. * \code
  69. * CWriterCallback oCallback("test.ebml");
  70. * EBML::IWriter* pWriter=EBML::createWriter(oCallback);
  71. * EBML::IWriterHelper* pWriterHelper=EBML::createWriterHelper();
  72. * pWriterHelper->connect(pWriter);
  73. * \endcode
  74. *
  75. * The use of the EBML writer looks something like this :
  76. *
  77. * \code
  78. * pWriterHelper->openChild(EBML_Identifier_Header);
  79. * pWriterHelper->openChild(EBML_Identifier_DocType);
  80. * pWriterHelper->setStr("EBML basic sample");
  81. * pWriterHelper->closeChild();
  82. * pWriterHelper->openChild(EBML_Identifier_DocTypeVersion);
  83. * pWriterHelper->setUInt(1);
  84. * pWriterHelper->closeChild();
  85. * pWriterHelper->closeChild();
  86. * \endcode
  87. *
  88. * Finally, we have to release the objects and to clean memory :
  89. *
  90. * \code
  91. * pWriterHelper->disconnect();
  92. * pWriterHelper->release();
  93. * pWriter->release();
  94. * \endcode
  95. */