aoiconftool

Generate Addon Interface (AOI) configuration files

Syntax:

aoiconftool [ -c config_file | -d directory [-p pattern] ] [-e] 
[-H] [-R] [ -h addon ] [ -r addon ] [ -i interface ]* [ -o output_file ]
[ -q[q...] | -v[v...] ] [ dllname1[ dllname2...] ]

Runs on:

QNX Neutrino

Options:

-c config_file

Base the configuration on the specified existing configuration file. This option is useful for adding or updating a cached summary of interfaces (see the “Configuration file syntax” section for details) to a manually written configuration, or validating an existing configuration (which happens if you don't name an output file with -o).

You must specify at least one of the -c or -d options or provide a list of DLL names (dllname1...) so the configuration has something to load.

If config_file doesn't start with a slash, it's treated as the base name for the file. For instance, a value of mmf makes the utility look for a file named mmf.conf in the configuration directory. If no matching file is found, the default file is loaded. If the value starts with a slash (“/”), it's treated as an absolute path and if the utility can't find that exact file, no default file is loaded. For more details, see “Names and location of configuration files”.

-d directory

Load addon DLLs from directory. All DLLs in the named directory will be loaded unless you specify a filename pattern with the -p option.

You must specify at least one of the -d or -c options or provide a list of DLL names (dllname1...) so the configuration has something to load.

-e

Save a cache section for all addons. The default behavior is to save it only for addons with a hold count of zero. For information about this section's purpose and contents, see the cache syntax description.

If you set the -e option, you can create a configuration that has non-zero hold counts for DLLs that you suspect should stay in memory, but also ensure their cache summaries are saved. This is handy if you want to manually change some hold counts to zero in the configuration file to see how this affects performance.

-H

Increment the global hold counter (like the AoHoldAll() library call). When this counter is non-zero, no DLL is unloaded from memory at least until the corresponding AoUnloadConfig() call reverts the effect. This avoids the overhead of loading and unloading any given DLL too often, but adds the potential overhead of keeping all DLLs in memory after their first usage.

-h addon

Increment the hold counter of the addon DLL with the given name (like AoFindName()). For information on how addons can define their own names, see the Name interface reference in the Addon Interfaces Library Reference. You can provide as many -h options as you like.

-i interface

Increment the hold counters of all addons that have the named interface. You can provide as many -i options as you like.

-o output_file

Save the new configuration to the specified file. The path can be absolute or relative. If the file exists, it is overwritten. The AOI configuration is written as a text file, with a format described in “Configuration file syntax”.

If you don't provide this option, the configuration will be validated, with the results written to the system log, but not saved.

-p pattern

Restrict the files that get loaded as DLLs based on the filename format given in pattern. For instance, specifying a pattern of streamer means aoiconftool will attempt to load DLLs that implement streamers but ignore those for parsers, decoders, and any other filters. This could be useful with libmmplaylist, which uses streamers to read playlists but does not use multimedia filters.

This option is considered only if -d is defined.

-q

Decrease verbosity. By default, aoiconftool logs information messages and anything more serious. You can specify one or more -q options to reduce what kinds of messages are logged, to limit the logging to warnings or errors of a certain serverity level.

-R

Decrement the hold counters for all addon DLLs so that no DLL's counter will be greater than zero even if the DLL increments it at startup. Some DLLs do this because they're not meant to be loaded and unloaded many times. When -R is set, they won't be loaded again until their first usages, instead of remaining loaded since startup and never unloaded.

-r addon

Decrement the hold counter for the addon DLL with the given name. If the counter is already zero, aoiconftool outputs a warning. If the counter is one and hence, becomes zero, the addon DLL is released from memory if the global hold counter is also zero.

For information on how addons can define their own names, see the Name interface reference in the Addon Interfaces Library Reference. You can provide as many -r options as you like.

-v

Increase verbosity. By default, aoiconftool logs information messages and anything more serious. You can specify one or more -v options to augment what kinds of messages are logged, to make the logging include debug messages of a certain level.

dllname1 dllname2 ...

Load the addons specified in the list of DLL names. Loading explicitly named DLLs is more flexible than loading all DLLs in a given directory, or even all of those with the same filename pattern, such as an extension type.

You must provide this list if you don't define either of the -c or -d options.

Description:

The aoiconftool utility generates Addon Interface (AOI) configuration files. These files tell the AOI library which DLLs to load and which configuration settings to apply to them. When an application wants to use certain addon features, it uses this library to load the appropriate configuration files. For more details, see the Addon Interfaces Library Reference.

The command-line options determine the new configuration's content. You can include the following information in the configuration:

The DLLs to load, based on an existing configuration, directory, or a provided list
Specific values for the global hold counter and the hold counters for individual addons
A cached summary of interfaces

You can run the utility without naming an output file, just to validate a possible configuration. In this case, aoiconftool attempts to load and configure the DLLs as indicated by the command line, and logs the outcome of these actions, allowing you to see if the configuration is valid for your system.

Names and location of configuration files

When loading a configuration through the AOI library, an application can provide the base name (i.e., a filename without a path or extension) of a configuration file to use, or use the default file. Typically, the base name reflects the functionality that the configuration is designed to support. For example, an application using the Metadata Provider library would request a base name of libmd. AOI configuration files end with the .conf extension, so in this case, the base name maps to a file named libmd.conf.

If the AOI library can't find the requested file, it loads the default file of default.conf. This design allows an application developer to define their own base name and the system integrator to decide whether to provide a customized file with that name or let the application use the default file. By default, the library looks for configuration files in /etc/system/config/aoi, but this path can be overriden with the AOI_CONFIG environment variable, which further increases flexibility for using custom files.

Note that applications can override any system setup by loading a configuration file at a specific path; for details, see the AoLoadConfig() entry in the Addon Interfaces Library Reference.

Using multiple configuration files

The AOI library maintains a global list of interfaces and updates this list when a configuration is loaded, based on the interfaces in the DLLs included by that configuration. Different application components can use different configurations but they all share the global list. The same DLL can be included in multiple configurations but its settings must be the same in each; otherwise, it's an error.

The library also keeps track of how many configurations have included a DLL and of the DLL's hold counter. When an application component unloads a configuration, the library decrements the hold counters and removes any interfaces from the list as necessary.

Configuration file syntax

AOI configuration files are text files that are interpreted as sequences of tokens. There are four kinds of tokens:

Keywords—reserved words that indicate the start of sections and subsections, all of which are described below. Keywords are not case-sensitive.
Strings—sequences of characters enclosed in double quotes (""). You can't have a newline inside of a string, but you can use these escape sequences: \n, \t, \r, \", or \\.
Integers—sequences of decimal digits, without a plus or minus sign; this means only non-negative values are supported
Punctuation—the only punctuation is the assignment operator (=)

Tokens can be separated by whitespace and comments. For whitespace, spaces and newlines can be used. If a keyword follows an integer, they must be separated by whitespace or a comment. Apart from that, whitespace outside of strings is not significant. For comments, a number sign (#) starts a comment (unless the character is embedded in a string) and the next newline ends it.

Each configuration file section or subsection is essentially a field setting that affects the AOI library's global list of interfaces and loaded DLLs. Often, this setting is just one line of text. Files are parsed from beginning to end, so the order of the sections is significant.

GlobalHolds

globalholds = integer

This setting increments the global hold counter by the provided value. Because no application should decrement the counter without having incremented it first, defining a non-zero value in this section ensures that any DLLs subsequently loaded into memory will stay in memory forever, or at least until this configuration is unloaded.

Dir

dir = string

Setting this field adds the interfaces in the DLLs found in the specified directory to the global list of interfaces. The AOI library will scan the directory and try to load every DLL it finds there. If the DLL's interfaces aren't already in the list, the DLL gets loaded, a summary of its interfaces is extracted and added to the global list, and then it gets unloaded if the global hold counter is zero.

DLL

dll = string [subsection]...

Setting the dll field adds the interfaces in the specified DLL to the global list of interfaces. The dll section can have subsections. Depending on which subsections are present, the DLL may or may not get loaded into memory, and then either get unloaded or be kept in memory.

Each of the following subsections is optional but may be specified only once in the same dll section (the order is insignificant):

config

config = string [string ...]

This field setting defines the configuration strings for the addon DLL. At least one string must be present. Each string is treated as a configuration setting. If it contains an equal sign (=), then the part before the first such character is treated as the name of the setting, and the part after as the value. If there's no such character, the entire string is the name.

What names and values are valid and what they mean is specific to the DLL. The DLL can also declare the type of a setting, as a string, numeric (integer or floating point), or boolean. Numeric settings must contain the equal sign and a valid numeric value, acceptable to strtoll() or strtof(). Boolean settings must be set to 0 or 1 or have no value at all (e.g., "EnableX=0", "EnableX=1", or "EnableX"). String settings without an equal sign are interpreted as empty strings (e.g., "Name=" and "Name" are equivalent).

holds

holds = integer

This field lets you increment the hold counter for the DLL by the provided value. When this counter is non-zero, this ensures that the DLL is kept in memory.

cache

cache = string ...

This field contains strings that are generated by aoiconftool; they can't be written manually. The strings store information about the DLL's interfaces that's normally kept by the AOI library when the DLL is not in memory. For aoiconftool, reading the cache contents is much faster than loading DLLs just to extract information.

Note: You should not modify the cache field in any way or copy it to a section that configures another DLL or even a new release of the same DLL.

These field settings cause the AOI library to do the following:

If the DLL's interfaces are already in the list, any value from the holds field is added to the DLL's hold counter. If this causes the counter to change from zero to non-zero, the DLL gets loaded.
If the DLL's interfaces are not in the list, they're added, and:
- If there's a holds field with a non-zero value, the DLL gets loaded and the field's value is added to the hold counter.
- Otherwise, if there's a cache field, the DLL does not get loaded.
- Otherwise the DLL gets loaded, its interfaces are examined and saved, and unless the global hold counter is non-zero, it gets unloaded.

Examples:

On some target systems, the DLLs that support common media operations are stored in a single directory whose path is assigned to the MM_INIT environment variable. You can generate an AOI configuration file that makes the AOI library read all DLLs in this directory and store their information without keeping them in memory:

# aoiconftool -d $MM_INIT -R -o /etc/system/config/aoi/default.conf

This is more efficient than loading all of the DLLs at startup and keeping them in memory because applications can query the AOI library to examine the available interfaces and load only those that they want to use (e.g., because they're the highest rated for specific media operations).

In the example above, the generated configuration is written to the default file at the default location (/etc/system/config/aoi/default.conf).

You can modify any generated configuration file with a text editor. For any addon that has configuration settings, you'll find these settings listed with their default values and short descriptions. You can modify the configuration values, and change the holds parameter from 0 to 1 for any DLL that you want kept in memory rather than loaded and unloaded on demand.

You can add the -e option to include cache summary information in the configuration. If you then update your DLLs to new versions, this summary will be out of date. The cache fields of a configuration file aren't meant to be modified, so in this case, you need to generate a new configuration based on the old one:

# aoiconftool -c default -o default.conf

The cache information from the old file is discarded, and new information is created based on the DLLs present on the target system. Any configuration settings are copied from the old to the new file, with unchanged values but updated descriptions. If a DLL's new version has configuration settings that the old version does not, these are added to the new file with default values. If some settings in the old file have become invalid in the new DLL version, the operation fails and you need to correct the settings manually.

In this last example, the aoiconftool utility reads the default configuration file and creates a new file named default.conf in the current directory. This is safer than asking the utility to overwrite the old file, because it could fail after destroying the old file but before creating a complete new one.