\hypertarget{core_concepts_public_interface}{}\section{Overview of the Public Interface}\label{core_concepts_public_interface}
The E\+B\+ML library is designed with a clear separation between an element\textquotesingle{}s metadata and factory functionality (the $\ast$type$\ast$$\ast$) and its actual data and behavior (the {\bfseries instance}). This allows you to\+:


\begin{DoxyItemize}
\item Create new elements from a high-\/level factory interface.
\item Decode raw E\+B\+ML data into usable element objects.
\item Encode elements back into E\+B\+ML format.
\item Access common information such as the element\textquotesingle{}s E\+B\+ML ID, name, size, and file location.
\end{DoxyItemize}

The core public interfaces are defined in the abstract classes\+:


\begin{DoxyItemize}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElementType}{ebml\+::ebml\+Element\+Type}}} Provides public member functions such as\+:
\begin{DoxyItemize}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElementType_ac19f5e622a88b5d03b6ecbc51e5ec656}{ebml\+::ebml\+Element\+Type\+::operator()()}}} to construct an element instance.
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElementType_aa48d60d852e4a8ecb42e33d6131324f7}{ebml\+::ebml\+Element\+Type\+::decode()}}} and {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElementType_a51300f338a81243ac16bed8964212a04}{ebml\+::ebml\+Element\+Type\+::cdecode()}}} for converting raw E\+B\+ML data into element instances.
\item Public data members exposing metadata (e.\+g. the E\+B\+ML ID and element name).
\end{DoxyItemize}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}} Offers a public interface for\+:
\begin{DoxyItemize}
\item Encoding the element into a binary representation through the {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a183d4d2f13bc8421054113333c3948d4}{ebml\+::ebml\+Element\+::encode()}}} functions.
\item Cloning the element through the {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_afde9d41a0e63dfd61014eb61d81f249b}{ebml\+::ebml\+Element\+::clone()}}} function.
\item Retrieving hierarchical relationships\+:
\begin{DoxyItemize}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a9a784c3c424216ecd4b320e2cfc713b2}{ebml\+::ebml\+Element\+::has\+Parent()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a2284de40bfd5b67a7668066a0f816296}{ebml\+::ebml\+Element\+::parent\+\_\+is\+\_\+const()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a205f4bdecb50b5c6b8db02fe1cceda20}{ebml\+::ebml\+Element\+::parent()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_ab1ae561c894f6662c64e4596cb0fa7d6}{ebml\+::ebml\+Element\+::c\+\_\+parent()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a9c9ed1823c036c8a77a64c68e12e769f}{ebml\+::ebml\+Element\+::root()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a3dddd3edbb6c96b8765107fccad5826b}{ebml\+::ebml\+Element\+::c\+\_\+root()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a1ee44e2978cd9e23c98cd9c05dd8fa35}{ebml\+::ebml\+Element\+::document()}}}
\end{DoxyItemize}
\item Accessing size and location information;
\begin{DoxyItemize}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a7d0d7a0277351c6ff00ac998303d3f70}{ebml\+::ebml\+Element\+::data\+Size()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a9305dc06339d900f81bd986653457e28}{ebml\+::ebml\+Element\+::head\+Size()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_afec544741c6640f3f328c643282c5c67}{ebml\+::ebml\+Element\+::size\+Width()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_aa6e265beb13dae353d75cdacc77748e1}{ebml\+::ebml\+Element\+::outer\+Size()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a10df5e4a342a2ec9682de0faec4f470c}{ebml\+::ebml\+Element\+::offset\+In\+Parent()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_ab9f3e77ee8dcab574942f5402619fbb9}{ebml\+::ebml\+Element\+::offset\+In\+File()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_ab6d5b99a9986587b7d1a806d6613faf3}{ebml\+::ebml\+Element\+::data\+Offset\+In\+Parent()}}}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement_a9b495834bf82f45ceaa81df19b7d643f}{ebml\+::ebml\+Element\+::data\+Offset\+In\+File()}}}
\end{DoxyItemize}
\end{DoxyItemize}
\end{DoxyItemize}

Notice that the public interface intentionally abstracts away complex internal details. The protected and private member functions focus on the implementation details of instance creation, decoding, and memory management.\hypertarget{core_concepts_basic_implementation}{}\section{Subclassing\+: Implementing a Fully Functional E\+B\+M\+L Element}\label{core_concepts_basic_implementation}
To implement a new E\+B\+ML element, you typically define a subclass pair\+:
\begin{DoxyItemize}
\item {\ttfamily ebmltype\+\_\+t}\+: A concrete subclass of {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElementType}{ebml\+::ebml\+Element\+Type}}} that encapsulates metadata and the factory methods.
\item {\ttfamily ebmlinst\+\_\+t}\+: A concrete subclass of {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}} that holds the actual element data.
\end{DoxyItemize}

This section outlines the essential requirements and optional recommendations for successfully implementing these subclasses.

A pair of C\+R\+TP templates {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlTypeCRTP}{ebml\+::ebml\+Type\+C\+R\+TP}}$<$ebmltype\+\_\+t, ebmlinst\+\_\+t, typebase\+\_\+t$>$} and {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElementCRTP}{ebml\+::ebml\+Element\+C\+R\+TP}}$<$ebmltype\+\_\+t, ebmlinst\+\_\+t, instbase\+\_\+t$>$} are provided to help simplify the process of subclassing {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElementType}{ebml\+::ebml\+Element\+Type}}} and {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}}. See \mbox{\hyperlink{crtp_usage}{The C\+R\+TP Design Pattern}} for more information.\hypertarget{core_concepts_type_implementation_requirements}{}\subsection{Requirements for \`{}ebmltype\+\_\+t\`{} (\+Element Type Subclass)}\label{core_concepts_type_implementation_requirements}
It is still possible, however, to subclass directly from {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElementType}{ebml\+::ebml\+Element\+Type}}} and {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}}. To do this, in your element type subclass, you must implement the following protected virtual functions\+:


\begin{DoxyItemize}
\item {\bfseries Mandatory Methods\+:}
\begin{DoxyItemize}
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}$\ast$ ebmltype\+\_\+t\+::\+\_\+new() const;} ~\newline
 Must create and return a new, default instance of your element instance ({\ttfamily ebmlinst\+\_\+t}).
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}$\ast$ ebmltype\+\_\+t\+::\+\_\+decode\+\_\+v(const ebml\+::parse\+String\&) const;} ~\newline
 {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}$\ast$ ebmltype\+\_\+t\+::\+\_\+decode\+\_\+v(const ebml\+::parse\+File\&) const;} ~\newline
 These functions must decode raw data (provided as a {\ttfamily \mbox{\hyperlink{classebml_1_1parseString}{ebml\+::parse\+String}}} or a {\ttfamily \mbox{\hyperlink{classebml_1_1parseFile}{ebml\+::parse\+File}}}) into an instance of your element.
\item {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}$\ast$ ebmltype\+\_\+t\+::\+\_\+cdecode\+\_\+v(const parse\+String\&) const;} ~\newline
 {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}$\ast$ ebmltype\+\_\+t\+::\+\_\+cdecode\+\_\+v(const parse\+File\&) const;} ~\newline
 Similar to the above, these functions decode data into a const instance.
\end{DoxyItemize}
\item {\bfseries Friend Declaration\+:} ~\newline
 In your element instance subclass ({\ttfamily ebmlinst\+\_\+t}), declare your element type class as a friend. For example\+: 
\begin{DoxyCode}
\textcolor{keyword}{friend} \textcolor{keyword}{class }YourEbmlTypeClass; \textcolor{comment}{// Replace with your actual type class name.}
\end{DoxyCode}

\item {\bfseries Optional Enhancements\+:} ~\newline
 Consider overloading {\ttfamily ebmltype\+\_\+t\+::operator()} in your {\ttfamily ebmltype\+\_\+t} subclass to provide convenient factory functions that allow construction of {\ttfamily ebmlinst\+\_\+t} objects using custom parameters.
\end{DoxyItemize}\hypertarget{core_concepts_inst_requirements}{}\subsection{Requirements for \`{}ebmlinst\+\_\+t\`{} (\+Element Instance Subclass)}\label{core_concepts_inst_requirements}
Your element instance subclass must at a minimum implement\+:


\begin{DoxyItemize}
\item {\bfseries Constructor Requirements\+:} ~\newline
 Define a constructor {\ttfamily ebmlinst\+\_\+t\+::ebmlinst\+\_\+t(const ebmltype\+\_\+t$\ast$)} that accepts a pointer to the companion {\ttfamily ebmltype\+\_\+t} (i.\+e. an instance of your element type class). ~\newline
 This constructor should invoke the protected constructor of {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}}.
\item {\bfseries Mandatory Methods\+:}
\begin{DoxyItemize}
\item {\ttfamily size\+\_\+t ebmlinst\+\_\+t\+::data\+Size() const;} ~\newline
 Must return the size of the element’s data (excluding header).
\item {\ttfamily size\+\_\+t ebmlinst\+\_\+t\+::\+\_\+encode(char$\ast$) const;} ~\newline
 Must encode the element (usually its data portion) into the provided buffer.
\item {\ttfamily ebml\+Element$\ast$ ebmlinst\+\_\+t\+::\+\_\+clone() const;} ~\newline
 Must create and return a deep copy of the element.
\item {\ttfamily std\+::wstring minirepr() const;} ~\newline
 Must return a concise wide string representation of the element.
\end{DoxyItemize}
\item {\bfseries Optional Overrides\+:} ~\newline
 You may override additional virtual functions to refine encoding behavior, add further validation, or to customize parent–child relationship management beyond the default implementations.
\end{DoxyItemize}\hypertarget{core_concepts_core_summary}{}\section{Summary}\label{core_concepts_core_summary}

\begin{DoxyItemize}
\item The {\bfseries public interface} of {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElementType}{ebml\+::ebml\+Element\+Type}}} and {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElement}{ebml\+::ebml\+Element}}} provides the essential tools for creating, decoding, and encoding E\+B\+ML elements without exposing the internal complexities.
\item To implement a concrete E\+B\+ML element\+:
\begin{DoxyItemize}
\item Subclass {\ttfamily \mbox{\hyperlink{classebml_1_1ebmlElementType}{ebml\+::ebml\+Element\+Type}}} as {\itshape ebmltype\+\_\+t} and implement the key virtual methods for instantiation and decoding.
\item Subclass {\ttfamily ebml\+Element} as {\itshape ebmlinst\+\_\+t} and implement the methods for encoding, cloning, and representing the element.
\item Declare your {\itshape ebmltype\+\_\+t} as a friend of {\itshape ebmlinst\+\_\+t} to allow controlled access to protected members.
\item Enhance your type class with overloads of {\ttfamily operator()} if you require customized construction logic.
\end{DoxyItemize}
\end{DoxyItemize}

This design encourages a robust, type-\/safe approach to working with E\+B\+ML data, making it accessible to both new and experienced C++ developers.

\begin{DoxySeeAlso}{See also}
\mbox{\hyperlink{crtp_usage}{The C\+R\+TP Design Pattern}} 

\mbox{\hyperlink{data_type_templates}{Data Type Templates\+: Creating Custom E\+B\+ML Data Types}} 
\end{DoxySeeAlso}
