Qeo Open Source Project Documentation : Tutorial: Creating the MediaEndPoint QDM

The Media Endpoint Topic

Let's reprise the Media Endpoint Topic. This is a producer or consumer of media files. In order to be able to clearly describe this topic, we also need to describe its properties:

Property	Description	Type
id	Unique ID of the media endpoint	String. We want to uniquely identify each Media EndPoint with the content of this string.
type	describes whether the endpoint is a producer or consumer of media	String equal to "SOURCE" or "SINK"
capabilities	Describes the supported media types, codecs and transports	String (MIME)
deviceId	Device identity representing the qeo device	DeviceId (standard Qeo ID format)

The diagram below shows the structure of the topic:

Step 1: Creating the Module Description

First of all, we will create a module in which to contain our data structure. We represent this with the <module> element. The module element must be encapsulated in the <types> element.

Icon

Although in theory it is possible to declare multiple modules inside a single XML file, the current version of the code generator does not support this yet. For now, we will therefore not do this.

We put only a single module in the XML file. the module name is "media".

Namespaces depend on the manufacturer. For Technicolor, we use two namespaces:

org::qeo for standardized QDMs
com::technicolor for non-standard Technicolor QDMs.

Suppose we are creating a standard The namespace is therefore org::qeo.

Since we want to use previously described data models, specifically DeviceID, we need to include the xml file that describes these models (qeo_types.xml). This results in the following XML structure:

<types xmlns="http://www.qeo.org/formal/2013/Qeo_Data_Model" version="0.1">
        <include file="qeo_types.xml"/>
        <module name="org::qeo::media">
 
 
 
       </module>
</types>

Step 2: Creating a Struct

Now that we have a module, we can add a struct. A <struct> element has two possible attributes:

name: name of the struct. We use "Endpoint" in the example.
behavior (optional): how the data type represented by the struct behaves (state or event). In the example, the media endpoint behaves as state.

The QDM now becomes:

<types xmlns="http://www.qeo.org/formal/2013/Qeo_Data_Model" version="0.1">
        <include file="qeo_types.xml"/>
        <module name="org::qeo::media">
            <struct name="Endpoint" behavior="state">
 
            </struct>
       </module>
</types>

Step 3: Creating the Members

Next, we want to represent properties of the media enpoint entity using the <member> element inside the mediaEnpoint <struct> element. The <member> element has the following possible attributes:

name: name if the member
type: the type of the member. This can be either one of the supported basic types (string, boolean, int8, int16, int32, int64, float) or non-basic
nonBasicTypeName (optional): used to indicate the name of the non-basic type if the value for type is not a basic type.
When referring to a type defined in the same XML file, you can use the regular, short name. However, when referring to a type created in a different XML, you need to use the fully qualified name with the complete namespace.
sequenceMaxLength (optional): used to indicate a sequence of types. The only value allowed is -1, indicating a sequence of indeterminate length. If this attribute is not declared, the member is a single value instead of a sequence.
key: indicates that this member is a key member. This means that the instance of the data type can be completely identified by the value of this member. The default value for this attribute is false. Since this example is State behaviour, the key field is mandatory and the value must be set to true.

About SequenceMaxLength

Icon

As "member" is a sequence. There can be any number of members. We use the sequenceMaxLength attribute to indicate this. Since Qeo only supports unlimited sequences at this point, we define the value of this attribute as -1. other values are not allowed (for now).

The table above shows us which members we need to define: id, type, capabilities and deviceID. The latter has a non-basic type, specifically DeviceID. The DeviceID struct is described in the qeo_types.xml file we included. The id member is a key member. This results in the following XML file:

<types xmlns="http://www.qeo.org/formal/2013/Qeo_Data_Model" version="0.1">
        <include file="qeo_types.xml"/>
        <module name="org::qeo::media">
            <struct name="Endpoint" behavior="state">
                <member name="id" type="string" key="true">
                </member>
                <member name="type" type="string">
                </member>
                <member name="capabilities" type="string">
                </member>
                <member name="deviceId" type="nonBasic" nonBasicTypeName="org::qeo::DeviceId">
                </member>
            </struct>
       </module>
</types>

For

Step 4: Documenting our QDM

In order to be able to easily reuse the QDM, or for others to use it, we need to document it. For this, we can insert <doc> elements in every level. Thus, we get our final QDM file:

<types xmlns="http://www.qeo.org/formal/2013/Qeo_Data_Model" version="0.1">
        <include file="qeo_types.xml"/>
        <module name="org::qeo::media">
            <struct name="Endpoint" behavior="state">
                <member name="id" type="string" key="true">
                    <doc>Unique ID of the media endpoint </doc>
                </member>
                <member name="type" type="string">
                    <doc>SOURCE (producer) or SINK (consumer)</doc>
                </member>
                <member name="capabilities" type="string">
                    <doc>Describes in a 'Internet media type'-way (MIME) the supported media types, 
                         codecs and transports e.g: content-type:application/sdp and the sdp can 
                         describe the supported codecs and transports</doc>
                </member>
                <member name="deviceId" type="nonBasic" nonBasicTypeName="org::qeo::DeviceId">
                    <doc>Device Id of the DeviceInfo datamodel</doc>
                </member>
            </struct>
       </module>
</types>

Icon

While you can define multiple structs inside a single XML file, this is not mandatory. You can create a separate QMD file for separate data types or group them as you see fit. Note, however, that since the current version of the Code Generator does not support multiple modules inside a single XML file, all of the structs in the same XML need to be in the same module.