Collapse all Symbian^3 Product Developer Library

CMI File Format

This section describes the format of the files loaded at startup by the Root Server Configurator. The files are known as Comms Module Ini (CMI) files and are used to describe Comms Provider Modules to be started by Root Server.

The files have an extension of .cmi.

Each Comms Module Ini file represents one Comms Provider Module for the Root Server Configurator to load.

File Location

Comms Module Ini files can be stored in the ROM of the device by placing the file in the \private\101f7988 folder. For example z:\private\101f7988\etel.cmi.

Comms Module Ini files can also be stored on other drives by placing the file in the same \private\101f7988 folder on the required drive. For example c:\private\101f7988\esock_ir.cmi.

The Comms Configurator searches for the Comms Module Ini files in the \private\101f7988 folders by searching from Y: to A: and then Z:. The folder 101f7988 is the secure area for the Comms Configurator process and its name derives from the UID for the process - as specified by the requirements for Data Caging. If the files are found in the ROM (usually Z:) they are not then copied to any other drive but only read in-place. Thus, a later configuration of Comms Module Ini files installed on another media/drive other than the ROM drive can be used to override the original ROM configuration. The Configurator reads these files only once during startup so any further changes will not take effect until the next time the system is started.

Syntax

Every Comms Module Ini file contains a [Loader] section, which contains the parameters that the Root Server Configurator must process. Optionally the Comms Module Ini files can also contain a [IniData] section which is read and sent in 8 bit form to the Comms Provider Module as part of the parameters to the main thread function.

Note: The data in the [IniData] does not need to follow the Comms Module Ini file format, since everything from the section header to the end of the file is passed verbatim to the Comms Provider Module.

The format of the [Loader] section of the file is:

Key = Value

For example

FileName=etel.dll

The keywords for the Loader section are summarised in the following table.

Keyword	Requirement	Default	Description
`Name`	Mandatory		The value specifies the server or CPM name to use in all references to this module, e.g. when enumerating loaded modules. This must be unique.
`Filename`	Mandatory		The host DLL containing the server or module
`IniData`	Optional		When present, the value is the name of an initialisation file whose contents are loaded into a descriptor and passed to the CPM as part of the parameters to the main thread function. The usage of this key overrides the usage of a `IniData` section within this file.
`IsSticky`	Optional	0 - Module can be unloaded	When present and with a value other than 0, specifies that clients cannot request the module to be shut down. The RootServer will return KErrLocked on such requests.
`ThreadFunctionOrdinal`	Optional		If not specified, or set to 0, it is assumed that the main thread function of the CPM is the default ordinal (which is the first ordinal in the export table - ordinal 1). If set to an integer number >0, the corresponding ordinal of the CPM DLL will be used as the main thread function. Anything else than 0 or a positive number is illegal.
`Priority`	Optional		When present, the value is an string value corresponding to the TThreadPriority enumerated type. The results of setting it to any other value will result in a KErrCorrupt error code.
`StackSize`	Optional		When present, the value is the integer size for the module’s main thread’s stack in bytes.
`StartSequence`	Optional		When present, the value is the integer start sequence. This is the legacy way of controlling the module start-up point and is translated into the ScaledStartupState.
`HeapOption`	Optional	Load into default heap	When present, controls whether the module is loaded with a new heap, attempts to share a heap, or simple uses the Root Server's heap. Values: `EDefaultHeap`, use the default shared heap for the process. `EShareHeap`, use the same heap as module defined by the option `ShareHeapWith`. `ENewHeap`, create module with a new heap.
`MinHeapSize`	Optional		If `HeapOption` is not `ENewHeap` this section is ignored. When present, specifies the minimum size in bytes of the Comms Provider Module's heap.
`MaxHeapSize`	Optional		If `HeapOption` is not `ENewHeap` this section is ignored. Specifies the maximum size in bytes of the Comms Provider Module's heap.
`ShareHeapWith`	Optional		If `HeapOption` is not specified as `EShareHeap`, this section is ignored, otherwise it is mandatory. When present specifies which CPM to share a heap with.
`BindingN`	Optional		Specify a Binding between two modules
`ScaledStartupState`	Optional		When present the value is the integer SSA start-up state, scaled up by `KC32StartupStateScalingFactor` (0x100).
`SystemCritical`	Optional	0	If set to 1, the Comms Provider Module runs as a System Critical thread.
`SystemCriticalAfterInit`	Optional	0	If set to 1, the Comms Provider Module runs as a System Critical thread once the Root Server Configurator has started all non-on-demand Comms Provider Modules.
`OnDemand`	Optional		Only load this Comms Provider Module when a client specifically requests it. Available only to Serial Communications Server files.
`Group`	Optional		The value contains the name of a group in which this Comms Provider Module belongs. Available only to Serial Communications Server files.

CMI File Format Examples

The following example shows a CMI file to load the Telephony Server:

## Comms Configurator config file for the ETel server

[Loader]
Name=CTelServer
FileName=etel.dll
ThreadFunctionOrdinal=233
IsSticky=1
IsServer=1
Priority=EPriorityNormal
StackSize=16384
ScaledStartupState=0x1085
HeapOption=ENewHeap
MinHeapSize=256
MaxHeapSize=786432
SystemCritical=1
ControlFlags=1

The following example shows a CMI file to load the IP thread for the Socket Server:

# Comms Configurator config file for the ESock IP Data worker

[Loader]
Name=ESock_DIP
FileName=esocksvr.dll
ThreadFunctionOrdinal=1
IsSticky=0
IsServer=1
Priority=EPriorityMuchMore
StackSize=16384
ScaledStartupState=0x3040
HeapOption=ENewHeap
MinHeapSize=256
MaxHeapSize=524288
SystemCritical=0
SystemCriticalAfterInit=1
Binding0=ESock_DIP:1,ESock_Main:0,ECustom,15,15
# Dont check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck)
ControlFlags=4
[IniData]
Role=DealerPlayer
WorkerId=1
EskMask=IP.*.ESK
PlayerRole=0x0001      # Hosting only data

The following example shows a CMI file to load the ECUART CSY into the second thread for the Serial Communications Server:

# c32_second - Comms Configurator config file forming part of the Default C32 server configuration


[Loader]
Name=C32_BaseBand
FileName=c32.dll
ThreadFunctionOrdinal=87
IsSticky=0
IsServer=1
Priority=EPriorityMuchMore
StackSize=16384
ScaledStartupState=0x1087
HeapOption=ENewHeap
MinHeapSize=256
MaxHeapSize=524288
SystemCriticalAfterInit=1
Group=C32SerComms
OnDemand=1
Binding0=C32_BaseBand:2,C32_Main:0,ECustom,42,42 
# Dont check heap if shutting down with EImmediate (KCF_ModuleImmediateNoCheck)
ControlFlags=4
[IniData]
Role=Player
WorkerId=2
CSYList=ECUART

Parent topic: Reference

Related concepts

What is the System Critical Parameter?

How to Configure Multithreaded C32 Serial Comms: Tutorial