Object properties: tips and tricks

If you've used Medialooks objects, you might have noticed that in addition to common configuration and initialization process, each Medialooks object has some special properties. This post talks about such properties and suggests some tips on how to use them.

Properties determine the object behavior in certain situations. In most cases there is no need to update the properties since they have been pre-configured for the most common use cases. However, in some cases, properties need to be changed. It is important that you understand the logic of reading and updating the properties.

When should I change the properties?

The default properties values fit most of the object use cases. So you should dig into the properties only when you get a recommendation to change it from the support team or from the documentation. 

What is each property responsible for? 

The easiest way to find out the properties description and possible values is checking the MPlatform and MFormats documentation. Almost each object section has its own article with a properties description table, it will give you the idea of what properties does this object have and what each one is used for. 

Storing and overriding the properties

There are several layers of property storage so that you can flexibly override them depending on your situation.

0. Inside the object initialization core. This is the zero level of property storage logic. The default properties for each object are stored inside its core. The main purpose of this layer is restoring the default property values in the main storage – the registry or the XML file (see below) – if they were deleted for some reason.

You have no access to this layer, so you cannot read or modify the properties in it. But you can use it to restore the factory default properties. Just clear the main storage content and default property values will be restored automatically on next object initialization. 

Note: you can delete just a single property or wipe the whole branch – the initialization core will detect the missing ones and restore them.

1. In the main property storage (the registry or the XML file). This is the first layer of properties storage logic. All newly created objects will use this values as default ones. By default all properties are stored in a registry here: 

[HKEY_CURRENT_USER\Software\Medialooks]

If you would like to keep properties in the XML file (for example if you don't have access to the registry), you need to create the empty Local.Config.xml file and place it in the same folders you keep the Medialooks.Runtime.dll. Here are the default locations:

"C:\Program Files (x86)\Medialooks\Medialooks Common\x86"
"C:\Program Files (x86)\Medialooks\Medialooks Common\x64"

Once the file is placed to these folders, all settings will be stored in this file instead of a registry. You can override the default property values by updating the registry or the XML file content. All newly created objects will contain the properties (including overridden ones) from the main storage. 

2. Inside of an application. This is the second layer. If you have multiple applications and want to customize some properties for each one independently, you can override the values from the main storage inside the application. You can override the properties using the IMFConfig interface of MFFactory class

// Create the factory class that will be used to update the properties 
MFFactoryClass factory = new MFFactoryClass(); 

// Get string with current properties values 
string currentSettings; 
factory.LoadSettings(@"MFormats\MFLive", out currentSettings); 

// Override some of them 
factory.SaveSettings(@"MFormats\MFLive", "no_signal.max_wait_msec='180' input.buffers='4'");

Note: if your main properties storage is the registry then overriding them will not have any effect on it. But if you store your properties in the XML file, then every change you make will also change the XML file.

3. Inside of a single object. This is the third and the last layer. No matter what properties have been set at the previous layers, you can always override them in a specific object using the IMProps interface:

MPlatform:
// Get current property value  
string myProperty; 
m_objPlaylist.PropsGet("loop", out myProperty); 

// Override it for this particular object  
m_objPlaylist.PropsSet("loop", "false");
MFormats:
// Get current property value 
string myProperty; 
m_objMFReader.PropsGet("network.buffer_min", out myProperty); 

// Override it for this particular object 
m_objMFReader.PropsSet("network.buffer_min", "2");

The overridden value will take effect on this particular object only within its lifetime and will not have any influence on other objects. 

Working with the IMProps interface

In addition to getting and setting the properties for a particular object, the IMProps interface gives you full control over the properties list: you can enumerate them, check each property description and possible values, etc.

Note: not all objects have property descriptions and details available through IMProps interface. We recommend referring to the MPlatform and MFormats documentation for the property descriptions.

Here is a generic code example of getting the property details with IMProps interface:

// Get the number of properties
var propsCount = 0;
m_pMFProps.PropsGetCount("", out propsCount);

// Let's check each property to get some more details about it.
for (int i = 0; i < propsCount; i++)
{
    // Let's take the property name and current value
    string strPropertyName, strValue;
    int isNode;
    m_pMFProps.PropsGetByIndex("", i, out strPropertyName, out strValue, out isNode);

    // Now, let's get some more information about the property
    // Check the help string. In most cases it contains the property description.
    string strHelp;
    m_pMFProps.PropsInfoGet(strPropertyName, eMInfoType.eMIT_Help, out strHelp);

    // Get the default value.
    string strDefault;
    m_pMFProps.PropsInfoGet(strPropertyName, eMInfoType.eMIT_Default, out strDefault);

    // Get the property type. It can be: integer, double, string, flags, option.
    string strType;
    m_pMFProps.PropsInfoGet(strPropertyName, eMInfoType.eMIT_Type, out strType);

    // If the property type is double or integer, we can get the Min and Max bounds for it's value.
    string strMinValue;
    m_pMFProps.PropsInfoGet(strPropertyName, eMInfoType.eMIT_Min, out strMinValue);
    string strMaxValue;
    m_pMFProps.PropsInfoGet(strPropertyName, eMInfoType.eMIT_Max, out strMaxValue);

    // If the property type is flag or option, we can get the possible values for it.
    string strValues;
    m_pMFProps.PropsInfoGet(strPropertyName, eMInfoType.eMIT_Values, out strValues);

    // If the property type is option, we can get the possible opsions for it.
    // Let's get the cuppent option value count first
    int optionIndex;
    string optionValue;
    string optionHelp;
    m_pMFProps.PropsOptionGet(strPropertyName, out optionIndex, out optionValue, out optionHelp);

    // Now let's take a look at other possible options
    // We need to get the options count first
    int optionsCount;
    m_pMFProps.PropsOptionGetCount(strPropertyName, out optionsCount);

    // Let's check each Option to get some more details about it.
    for (int j = 0; j < optionsCount; j++)
    {           
        // Get the option value and option description
        string currentOptionValue;
        string currentOptionHelp;
        m_pMFProps.PropsOptionGetByIndex(strPropertyName, j, out currentOptionValue, out currentOptionHelp);
    }
}