1 #######################################

     2 Configuration ML Specification Document

     3 #######################################

     4 

     5 **Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).** All rights reserved. This component and the accompanying materials are made available under the terms of "Eclipse Public License v1.0" which accompanies this distribution, and is available at the URL "http://www.eclipse.org/legal/epl-v10.html".

     6 

     7 

     8 ==================

     9 Table of contents:

    10 ==================

    11 

    12 .. contents::

    13 

    14 ===================

    15 1. Document Control

    16 ===================

    17 

    18 1.1 References

    19 --------------

    20 

    21 #. Customization tool interoperability Requirements Specification

    22    http://www8.connecting.nokia.com/nmp/msw/tsw/series60/series60dm.nsf/WebAllByID/XXXJ16313-EN

    23 #. XML Inclusions (XInclude) Version 1.0, W3C Recommendation, 20 December 2004

    24    http://www.w3.org/TR/xinclude/

    25 #. Extensible Markup Language (XML) 1.0 (Third Edition), W3C Recommendation,

    26    http://www.w3.org/TR/2004/REC-xml-20040204

    27 #. Modularization of XHTML, W3C Recommendation

    28    http://www.w3.org/TR/2001/REC-xhtml-modularization-20010410

    29 #. XML Linking Language (XLink) Version 1.0, W3C Recommendation, 27 June 2001

    30    http://www.w3.org/TR/xlink/

    31 #. XML Path Language (XPath) Version 1.0, W3C Recommendation, 16 November 1999

    32    http://www.w3.org/TR/xpath

    33 #. XML Schema Part 2: Datatypes Second Edition, W3C Recommendation, 28 October 2004

    34    http://www.w3.org/TR/xmlschema-2/

    35 #. XHTML(TM) 2.0 - W3C Working Draft 22 July 2004

    36    http://www.w3.org/TR/xhtml2/

    37 #. Extending and Versioning XML Languages with XML Schema

    38    http://www.pacificspirit.com/Authoring/Compatibility/ExtendingAndVersioningXMLLanguages.html

    39 #. 

    40 #. RELAX NG Specification, OASIS Committee Specification, 3 December 2001

    41    http://www.relaxng.org/spec-20011203.html

    42 #. Uniform Resource Identifiers (URI): Generic Syntax, August 1998

    43    http://www.ietf.org/rfc/rfc2396.txt

    44 #. S60 Customization Tool

    45    http://s60wiki.nokia.com/S60Wiki/S60_Customization_Tool

    46 

    47 1.2 Glossary

    48 ------------

    49 

    50 .. glossary::

    51 

    52    Central Repository

    53       `Symbian OS <http://s60wiki.nokia.com/S60Wiki/Symbian_OS>`_ service that provides a user interface to allow one or more clients to open repositories, and to provision and retrieve information from those repositories.

    54    Configuration

    55       Specific values for a collection of settings. Used to configure terminal SW for certain platform release, product or trade customer (for example operator). In Configuration ML the root element of the language and includes also feature and setting definitions.

    56    Configuration element

    57       Defines a `configuration <http://s60wiki.nokia.com/S60Wiki/S60_Terminal_SW_Configuration>`_  capability of software. Is used to define using one or more settings or features.

    58    Configuration enabler

    59       A software functionality that at runtime implements configurability for one or more setting

    60    Configuration Tool

    61       Tool used for configuring SW build (for example variant)

    62    ConfML

    63       Configuration Markup Language, language defined in this document

    64    Customization Tool

    65       S60 specific tool to configuring SW build (for example variant). Replaced by Configuration Tool. 

    66    Extension policy

    67       A mechanism for controlling how sequence item-settings for single setting in multiple configurations are handled.

    68    Feature

    69       A collection of related settings.

    70    Group

    71       For structuring settings in view.

    72    Item-setting

    73       A single item in a data of a sequence setting. Each item-setting defines values for sub-settings. For example, every contact in a data for phone book setting is an item-setting.

    74    lowerCamelCase

    75       Practice of writing `compound words <http://en.wikipedia.org/wiki/Compound_noun_and_adjective>`_ or phrases in which the words are joined without `spaces <http://en.wikipedia.org/wiki/Whitespace_%28computer_science%29>`_ and are `capitalized <http://en.wikipedia.org/wiki/Capitalization>`_ with the exception of the first word within the compound (http://en.wikipedia.org/wiki/CamelCase).

    76    Option

    77       Allowed value for a setting.

    78    Restore Factory Settings (RFS)

    79       Feature for reinitialising device data to factory settings stored on ROM.

    80    Setting

    81       Defines a single configurable element (for example mailbox name).

    82    Setting implementation

    83       Information about platform specific implementation. Used when building a configuration. Specific for the used configuration enabler

    84    Sub-configuration

    85       A configuration included in other configuration.

    86    Sub-setting

    87       Individual setting data elements that are available for each item-setting of a sequence data. For example, phone number field of every contact item-setting is a sub-setting.

    88    Value

    89       Defines a value of a setting. Single customizable value of a certain setting. For example Mailbox name.

    90    Variant 

    91       A specific kind of configuration. Term used in Customization Tool for customer specific values.

    92    View

    93       For rearranging settings into new structure and redefining their properties regardless how they where defined originally.

    94 

    95 ===============

    96 2. Introduction

    97 ===============

    98 

    99 2.1 Purpose and scope

   100 ---------------------

   101 

   102 Configuration ML (later in document 'Configuration ML' or 'ConfML') is a XML-based markup language (that is, an XML application) for defining SW configuration elements and configuration data of SW product. 

   103 

   104 Configuration ML is an evolution of XML language designed and used for S60 Customization Tool. Full compatibility with the tools already supporting so-called variant data files of earlier format was first seen as important. However, it was afterwards seen that compatibility would only make Configuration ML more complicated than needed. Also new features of such as mapping Boolean settings to bitmasks key in Central Repository and enabling incremental definition of sequences would have not been supported by old format. Therefore The Configuration ML is not compatible with variant features or variant data XML formats used by S60 Customization Tool. On the other hand it is possible to develop tools that support reading and/or writing both formats. Configuration ML language itself is not S60 specific and therefore can be used also outside S60.

   105 

   106 2.2 Main concepts

   107 -----------------

   108 

   109 The Configuration ML consists of four plus one main components as shown in Figure 1.

   110 

   111 .. image:: images/configurationml085-f1.gif 

   112 

   113 Figure 1 The main components of Configuration ML

   114 

   115 Configuration ML is primarily used to define configurations, features, settings, and data. The fourth component is Restore Factory Settings component, rfs. All these components are optional. Configuration is the top level concept of the language. It groups together relevant configuration features and values for them. Features consist of settings. Configurations are typically defined incrementally, and therefore configuration can be defined by means of any number of other configurations. Chapter 3 explains in detail the main concepts of the language.

   116 

   117 Setting implementation definitions are defined using separate languages, which are defined in separate documents. One of the main goals of Configuration ML is to separate the logical feature definitions from the actual implementation specific details. Setting implementation definitions contain all the required logic to convert values in data part to implementation specific values that are used either at ROM image creation time or by the terminal software at runtime.

   118 

   119 2.3 Applicability

   120 -----------------

   121 

   122 This specification defines how Configuration ML can be used to define all SW related configurability aspects of a software system. 

   123 

   124 Configuration ML is most typically used for those local or global functionality and user experience related configuration elements that are used for localization, differentiation and customization purposes.

   125 

   126 When defining configuration elements in using Configuration ML suitable abstraction level should be selected. In complex cases it might be better to use for example domain specific language and external file to describe the fine details, and only then have selection of an external file as a setting in Configuration ML. This approach also enables to build dedicated (possible graphical) tools to define the internal details of the element.

   127 

   128 2.4 Namespace

   129 -------------

   130 

   131 All the elements of Configuration ML are defined in a single versioned namespace called http://www.s60.com/xml/confml/2 . The namespace is updated for major, possibly non-backward compatible versions only. New minor versions must maintain compatibility. The root element of the document, configuration, must contain an xmlns declaration for this namespace. None of the attributes in this specification belong to any namespaces and therefore are never prefixed.  

   132 

   133 Example::

   134 

   135   <configuration xmlns="http://www.s60.com/xml/confml/2" />

   136 

   137 When elements of Configuration ML are stored in a separately included file, namespace needs to be redefined. Refer to chapter 3.2.3 for more information on how to use multiple files to define a configuration.

   138 

   139 The setting implementation information is defined in implementation specific namespace.  

   140 

   141 The namespace of Configuration ML must not be used for any other elements than defined in this document. All extensions must be therefore defined in some other namespace.

   142 

   143 2.5 MIME types and file name extensions

   144 ---------------------------------------

   145 

   146 The MIME type for XML files of Configuration ML is 'text/application+xml'. 

   147 

   148 It is recommended that all Configuration ML files use file name extension '.confml' (all lowercase) on all platforms.

   149 

   150 The file name extensions of setting implementation XML files are implementation specific.

   151 

   152 2.6 Reuse and Extensibility

   153 ---------------------------

   154 

   155 Configuration ML relies heavily on other existing XML language. Following XML languages are used one way or another: XPATH [6], XInclude [2], and XML schema [7].

   156 

   157 XPath is a language for addressing parts of an XML document. In support of this primary purpose, it also provides basic facilities for manipulation of strings, numbers, and Booleans. XPath uses a compact, non-XML syntax to facilitate use of XPath within URIs and XML attribute values. XPath operates on the abstract, logical structure of an XML document, rather than its surface syntax. Refer to chapter 3.4 and 3.3.2 for more information on XPath expressions are used in configuration ML.

   158 

   159 XInclude is a standard for assembling XML instances into another XML document through inclusion. It enables larger documents to be dynamically created from smaller XML documents without having to physically duplicate the content of the smaller files in the main file. Refer to chapter 3.2.3 for more information on working with multiple files.

   160 

   161 Configuration ML itself is designed to be extensible meaning that it can be further developed by defining new elements in own namespace.  

   162 

   163 2.7 Validation and usage

   164 ------------------------

   165 

   166 This document is the official definition for the Configuration ML XML language.

   167 

   168 All Configuration ML documents must be valid XML 1.0 documents. The applications and tools supporting Configuration ML are assumed to check the well-formedness of the Configuration ML document instances.  

   169 

   170 Every Configuration ML document should have XML declaration with version as the first thing in the file. 

   171 

   172 The root element of every Configuration ML document must be configuration. The version attribute for this element must be specified as '1.0'.

   173 

   174 Example::

   175 

   176   <?xml version="1.0"?>

   177     <configuration xmlns="http://www.s60.com/xml/confml/2" version="1.0">

   178     <!-- the body of the document -->

   179     </configuration>

   180 

   181 2.8 Localization

   182 ----------------

   183 

   184 As all XML documents, Configuration ML supports both UTF-8 and UTF-16 encodings. It is recommended to declare used encoding with XML declaration. This declaration is mandatory when other encoding than UTF-8 or UTF-16 is used. By default, UTF-8 encoding should be used, in case there is no good reason to do otherwise.  

   185 

   186 Example::

   187 

   188   <?xml version="1.0" encoding="UTF-8"?>

   189   <!-- the rest of the document ->

   190 

   191 Any characters from Unicode character set can be written in XML using XML Numerical Character Reference syntax: &#<decimal_character_code>; or &#x<hex_character_code>; .  

   192 

   193 ======================================================

   194 3. Overview

   195 ======================================================

   196 

   197 3.1 Components of Configuration ML

   198 ----------------------------------

   199 

   200 Figure 2 depicts the main elements of Configuration ML language and how they map to implementation elements.

   201 

   202 .. image:: images/configurationml085-f2.gif 

   203 

   204 Figure 2 The main elements of Configuration ML

   205 

   206 The elements shown in yellow are part of the Configuration ML. The elements shown in blue are implementation specific elements. For most of the Configuration ML elements shown in the Figure 2 there is a corresponding XML element. Those elements are defined in chapter 6. The elements named inside brackets represent either feature or setting specific XML elements as explained in chapter 3.4. The cardinalities of the elements are shown next to the connecting lines. The proximity of the cardinality marking defines the reading direction, for example "configuration can have any number of features".

   207 

   208 3.2 Configuration

   209 -----------------

   210 

   211 Configuration is the top level concept in Configuration ML. Configuration has three main roles:

   212 

   213 1. Defines configuration elements in terms of features and settings (chapter 3.3)

   214 2. Defines views for visually rearranging settings (chapter 3.5)

   215 3. Defines data (values) for settings (chapter 3.4)

   216 

   217 Any configuration can have all the above rules or just one of them. Configuration can also just contain other configurations as explained in chapter 3.2.2.

   218 

   219 3.2.1 Release specificity

   220 ^^^^^^^^^^^^^^^^^^^^^^^^^

   221 

   222 Configuration ML is agnostic to versioning of software. Managing multiple versions of software component(s) that have varying configurability capabilities will typically require multiple (independent) Configuration ML documents. Release element of meta element can be used to identify the release of a software component, platform or product in question if required.

   223 

   224 3.2.2 Hierarchical configurations

   225 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   226 

   227 Configurations are not typically defined in isolation, but they are parts of other configurations. To support this configuration can contain any number of other configurations (also called 'sub-configurations') as shown in the Figure 2. This enables features (including their settings), views, and data of a configuration to be defined using other configurations, which all can also be used independently of the including configurations when needed. The containment hierarchy of configurations would typically follow software or product architecture, or/and organisation developing the software or product.

   228 

   229 For example when defined according to software architecture of a terminal product, there would be a 'master' configuration for the product itself that could include configurations of manufacturer specific platforms. These platform configurations could itself consist of configurations defining each architecture domain and eventually each subsystem and component in the platform. Each of these component configurations could define the relevant features, settings, and default values, while including configurations typically refine the values further.  

   230 

   231 Each of the configurations can be created and used independently, in case they contain all the required includes so that referred setting definitions can be found. In addition they might override some or all the default values of the settings defined in included configurations.

   232 

   233 Please note that only data (that is, setting values) of the contained configurations can be overridden but not views, features, or settings.

   234 

   235 As a special case data of sequential settings can also be defined incrementally. In this case configuration extends (as a contrary to overriding) data of a setting that is defined in any of the included sub-configurations.

   236 

   237 3.2.3 Structuring configurations to files

   238 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   239 

   240 Typically features need to created and maintained by several persons/organisation and therefore storing all feature definitions into one file would cause problems. The definitions of a configuration can be split to any number of XML files by using include elements of XInclude specification [2]. Therefore it is possible to have each of the sub-configurations in own files. The only constraints are that every included file itself must be a complete valid Configuration ML XML document (that is, with configuration as the root element). When using multiple Configuration ML files it is also important to make sure that every feature and setting is defined only once. Refining features or setting is not allowed except when using view definitions (see chapter 3.5).

   241 

   242 When under single root configuration there exists multiple configurations with each own values, the priority of the values depends on the order: values later in XML document tree traversal order overrides any earlier values.

   243 

   244 An example hierarchy of files is shown in Figure 3.

   245 

   246 .. image:: images/configurationml085-f3.gif 

   247 

   248 Figure 3 An example hierarchy of configuration files

   249 

   250 In the example, there is two full configurations, one for product family and other for product variant (customised by operator). These configuration are composed by using includes. In a way, product family configuration is a subset of product variant configuration, and thus product variant could also include product family configuration and refine it further with product and variant specific definitions. However having each of the stakeholder represented as an a independent configuration, allows composing any kind of configuration more freely (e.g. free ordering, selecting only a subset). The order of inclusions defines also the override order, effectively acting as a method to define the inheritance order of configurations.

   251 

   252 Only a subset of XInclude specification is required[1] to be supported with Configuration ML. First of all, support for inclusion of local resources with relative URI is required. All included resources are to be parsed as xml and therefore parse attribute is not required. Also, support for xi:fallback element is not required. Refer to chapter 4.5 for complete list of supported attributes of xi:include element.

   253 

   254 .. [1] "Required" means here that some tools might choose to support more that what is required by this specification but must not assume the same from other tools.

   255 

   256 3.3 Features and settings

   257 -------------------------

   258 

   259 3.3.1 Defining features and settings

   260 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   261 

   262 Each configuration defines zero or more configuration elements in terms of features and settings. A feature groups together related settings. One setting describes a certain configuration capability implemented in software. Every feature must be identified uniquely using ref attribute. Each feature must be unique and defined only once in configuration including any sub-configurations included in it. In the same way every setting must be uniquely identified inside a feature. Once feature or setting is defined, it cannot be anymore redefined or extended elsewhere in the configuration.  

   263 

   264 3.3.2 Linking implementation to settings

   265 ----------------------------------------

   266 

   267 Implementations of settings are defined in a separate file(s) as already shown in Figure 2. No implementation is defined on feature level but every setting can and should have its own implementation. Relative XPATH location path definitions are used to link the setting implementations to the settings. To create a location path that is unique in the configuration the ref path of the feature and setting is concatenated together.

   268 

   269 3.4 Data

   270 --------

   271 

   272 3.4.1 Defining values

   273 ^^^^^^^^^^^^^^^^^^^^^

   274 

   275 One of the main roles of configuration is to define values for settings. Values can be defined only for settings that have been declared in the configuration (including any sub-configurations). Although there can be only one data element containing the values in a configuration, all sub-configuration can also contain own data elements and therefore also values.

   276 

   277 When values can be defined for settings in multiple places inside a configuration, it is important to understand the priority rules for interpreting them. One of the main use cases of Configuration ML is to allow overriding values of settings that were already defined in the included configuration. This is accomplished by utilizing normal xinclude expansion rules. In principle, include statements found from a configuration are expanded so that included document becomes a part of the including document. Prioritization of overrides is done by ordering the inclusions properly in the configuration.

   278 

   279 Figure 4 shows example configuration hierarchy on top, and the processed (expanded) version on the bottom. In this example, value 3 is applied to setting A/B.

   280 

   281 .. image:: images/configurationml085-f4.gif

   282 

   283 Figure 4 Priority of values

   284 

   285 As a special case, data of sequential settings can also be defined incrementally. In this case configuration can optionally extend (as a contrary to overriding) data of a setting that is defined in any of the included sub-configurations. This behaviour is controlled using extension policy of the setting data element (chapter 6.9). The extension can either append the new data to the end of existing data or prefix the existing data. If every configuration in the Figure 4 would contain value with append policy, then the actual data of that setting would be constructed in order of inclusions; first item(s) would be used from sub3.confml and the last items from the main configuration.

   286 

   287 Most of the settings defined in configurations are meant to be configured on product or customer level. In order to allow defining the value of read-only attribute, values defined for settings that are defined directly in the same configuration do not need to obey read-onlyness statement of setting. Essentially this means that read-only settings can be modified locally in the defining configuration (which is usually in the same file as the setting definition), in other configurations (usually in other files) it is locked for modifications.

   288 

   289 A configuration can directly define value at most only once of each setting.

   290 

   291 3.4.2 Linking settings and values

   292 ---------------------------------

   293 

   294 Values of a configuration are defined using element. Values can be defined for zero or more settings. Relative XPATH[6] paths are used to link values to settings on two levels: first on feature level and then on a setting level. See Figure 5 for illustration of how ref attributes are used.

   295 

   296 .. image:: images/configurationml085-f5.gif 

   297 

   298 Figure 5 Linking settings and values

   299 

   300 Elements under data elements that do not match to any setting should be preserved during all processing but can be excluded from validation.

   301 

   302 3.5 Views

   303 ---------

   304 

   305 View definitions in configurations can be used to visually  rearrange selected features and settings into new structure regardless how they where defined originally. By default settings are clustered according to features they are defined in but with views this can be overridden by use of group elements. Support for hierarchical groups is not limited.

   306 

   307 Any number of views can be defined in a configuration (including its sub-configurations) and it is up to tool or user of the tool to choose the active view if and when needed. Views are useful for creating for example terminal product specific views that show only the relevant settings and hide all the others. In addition to grouping selected features and settings, additional setting and option definitions can also be defined. This can be used for example to provide additional documentation for the user or to allow only restricted set of values to be defined. These additional definitions must never change the original meaning of the settings but can only restrict valid values even further from what was defined in the original setting definition. Therefore set of valid values according to the view must be a subset of valid values, as defined by the original setting definition. When validating data it is possible to use these additional restrictions in the active views also. As an example, if setting was originally defined to accept only values from 3 to 100, a view can add additional constraint that only allows odd numbers between 50 and 100. However, it would be illegal for view to define range from 2 to 110.

   308 

   309 It is important to note that view only affects how the features, settings, and values are visualized and optionally validated. The view must not have any effect to meaning (including type and data reference) of it or existence of data, when using data for example for building a configuration. Therefore all constraints and dependencies in original setting definitions apply whether or not the features and/or settings are part of the active view.

   310 

   311 ================================

   312 4. Common definition conventions

   313 ================================

   314 

   315 This document defines Configuration ML language and its semantics. This section describes the conventions used in Configuration ML. These conventions are based on [4].

   316 

   317 4.1 Structure

   318 -------------

   319 

   320 The language definition is structured in the following way:

   321 

   322 - An abstract definition of the elements, attributes, and content models, as appropriate.

   323 - A sub-section for each element; These sub-sections contain the following components:

   324 

   325  - A brief description of the element,

   326  - A definition of each attribute or attribute collection usable with the element, and

   327  - A detailed description of the behaviour of the element, if appropriate.

   328 

   329 Examples are provided with most of the definitions. Please note that they typically only show the element and attribute relevant for the definition in question, and therefore should not be taken as complete Configuration ML examples. More complete examples are provided in implementation markup language specifications.

   330 

   331 4.2 Syntactic Conventions

   332 -------------------------

   333 

   334 .. list-table::

   335 

   336    - - expr ?

   337      - Zero or one instances of expr are permitted.

   338    - - expr +

   339      - One or more instances of expr are required.

   340    - - expr *

   341      - Zero or more instances of expr are permitted.

   342    - - a ; b

   343      - Expression a and b are required in no specific order.

   344    - - a , b

   345      - Expression a is required, followed by expression b.

   346    - - a | b

   347      - Either expression a or expression b is required.

   348    - - a - b

   349      - Expression a is permitted, omitting elements in expression b.

   350    - - parentheses

   351      - n is contained within parentheses, evaluation of any sub-expressions within the parentheses take place before evaluation of expressions outside of the parentheses (starting at the deepest level of nesting first).

   352    - - defining required attributes

   353      - When an element requires the definition of an attribute, that attribute name is followed by an asterisk (*).

   354    - - defining the type of attribute values

   355      - When a module defines the type of an attribute value, it does so by listing the type in parentheses after the attribute name.

   356    - - defining the legal values of attributes

   357      - When the legal values are defined for an attribute, it does so by listing the explicit legal values (enclosed in quotation marks), separated by vertical bars (|), inside of parentheses following the attribute name. If the attribute has a default value, that value is followed by an asterisk (*). If the attribute has a fixed value, the attribute name is followed by an equals sign (=) and the fixed value enclosed in quotation marks.

   358 

   359 4.3 Content Types

   360 -----------------

   361 

   362 Minimal, atomic content models are defined for each element. These minimal content models reference the elements in the language itself. They may also reference elements in other languages upon which the language depends. Finally, the content model in some cases requires that text be permitted as content to one or more elements. In these cases, the symbol used for text is PCDATA[3]. This is a term refers to processed character data. Content type can also be ANY, meaning that any elements can be supported. A content type can also be defined as EMPTY, meaning the element has no content in its minimal content model.

   363 

   364 4.4 Attribute Types

   365 -------------------

   366 

   367 Following table lists definitions for all used XML attribute types. 

   368 

   369 .. list-table::

   370 

   371    - - Attribute Types

   372      - Definition

   373    - - CDATA

   374      - Character data [3]

   375    - - IDREF

   376      - A reference to a document-unique identifier [3]

   377    - - NMTOKEN

   378      - A name composed of only name tokens as defined in XML 1.0 [3]. All leading and trailing whitespace is removed but no whitespace is allowed within the value itself.

   379    - - NMTOKENS

   380      - A whitespace separated list of NMTOKENs.

   381    - - NUMBER

   382      - Sequence consisting only digits ([0-9]) [3]

   383    - - URI

   384      - A Uniform Resource Identifier [12].

   385    - - XPATH (path)

   386      - An XPATH [6] location path. Support for only relative element location paths defined in abbreviated syntax is required. Only subset of XPATH language is supported; refer to examples for details.

   387    - - 

   388      - 

   389    - - xs:token

   390      - Whitespace-replaced and collapsed strings as defined in XML Schema [7]. In addition to removing all leading and trailing whitespace, also all consecutive spaces, carriage returns, linefeeds and tabs within the value itself are replaced by a single space.

   391 

   392 4.5 Naming conventions

   393 ----------------------

   394 

   395 Element, attribute, and type names are composed of words in the English language, using the British English spellings.

   396 

   397 Lower Camel Case (LCC) is used for naming attributes, elements, and types. Lower Camel Case capitalizes the first character of each word except the first word and compounds the name.

   398 

   399 =====================

   400 5. Common definitions

   401 =====================

   402 

   403 This chapter contains common attribute and element definitions used by elements in Configuration ML and setting implementation languages.

   404 

   405 .. list-table::

   406 

   407    - - Elements

   408      - Attributes

   409      - Content Model

   410    - - `elements supporting CommonAttrs <#_Common_attributes_(CommonAttrs)>`_

   411      - id (NMTOKEN)

   412      - N/A

   413    - - `meta <#_Meta_elements>`_

   414      - CommonAttrs

   415      - id?; date?; owner?; editor?; status?; version?; platform?; product?; release?; customer?; origin?; target?; desc?; icon?; link*

   416    - - `desc <#_The_desc_element>`_

   417      - CommonAttrs, xl:href (URI), xl:title (CDATA)

   418      - PCDATA

   419    - - `icon <#_The_icon_element>`_

   420      - CommonAttrs, xl:href* (URI), xl:title (CDATA)

   421      - EMPTY

   422    - - `link <#_The_link_element>`_

   423      - CommonAttrs, xl:href* (URI), xl:title (CDATA)

   424      - EMPTY

   425    - - xi:include

   426      - CommonAttrs, href* (URI)

   427      - EMPTY

   428 

   429 Elements starting with xi namespace prefix are defined in XInclude[2]. Only listed attributes are supported for those elements. The rest of the elements are defined in the following sections.

   430 

   431 5.1 Common attributes (CommonAttrs)

   432 -----------------------------------

   433 

   434 The CommonAttrs attribute collection defines common attributes used by all Configuration ML elements. These attributes don't belong to any namespace and therefore must not be prefixed. These attributes are optional always.

   435 

   436 .. list-table::

   437 

   438    - - Attributes name

   439      - Type

   440      - Default

   441      - Description

   442    - - id

   443      - NMTOKEN

   444      - not defined

   445      -  The identifier of an element. Not used within language for identification. If defined ) the id of an element must be unique within the user interface definition. Typically descriptive ids that describe the purpose of the element should be used.

   446 

   447 Example::

   448 

   449   <feature id="myfeatureid">

   450    <setting id="thesetting"/>

   451   </feature>

   452 

   453 5.2 Meta elements

   454 -----------------

   455 

   456 The meta elements define common metadata for certain elements in configuration and setting implementation documents. The meta element is the parent for all other meta elements. Typically meta element is the first child of the root element. None of the meta elements have any attributes but all the content is defined as PCDATA.

   457 

   458 In addition to common elements the following meta specific elements are defined in this specification.

   459 

   460 .. list-table::

   461 

   462    - - Elements

   463      - Attributes

   464      - Content Model

   465    - - id

   466      - CommonAttrs

   467      - PCDATA

   468    - - date

   469      - CommonAttrs

   470      - PCDATA in the format CCYY-MM-DD\[z\|\(-\|+\)hh\:mm\]

   471    - - owner

   472      - CommonAttrs

   473      - PCDATA

   474    - - editor

   475      - CommonAttrs

   476      - PCDATA

   477    - - status

   478      - CommonAttrs

   479      - PCDATA

   480    - - version

   481      - CommonAttrs

   482      - PCDATA

   483    - - platform

   484      - CommonAttrs

   485      - PCDATA

   486    - - product

   487      - CommonAttrs

   488      - PCDATA

   489    - - release

   490      - CommonAttrs

   491      - PCDATA

   492    - - customer

   493      - CommonAttrs

   494      - PCDATA

   495    - - origin

   496      - CommonAttrs

   497      - PCDATA

   498    - - target

   499      - CommonAttrs

   500      - PCDATA

   501 

   502 The date is defined according to data type 'date' of XML Schema [7]. UTC time zone can be defined with letter Z at the end of the date string. Other time zones are represented by their difference from UTC in the format +hh:mm or -hh:mm. If no time zone is defined then it is undefined. Meta element can be extended by defining new child elements in a separate namespace.

   503 

   504 Example::

   505 

   506   <configuration>

   507    <meta>

   508     <date>2006-06-19</date>

   509     <owner>John Smith</owner>

   510     <editor>John smith Junior</editor>

   511     <status>draft</status>

   512     <platform>S60</platform>

   513     <product>N99</product>

   514     <release>3.9</release>

   515     <desc>Reference configuration</desc>

   516     <customer>MegaOperator</customer>

   517    </meta>

   518   </configuration>

   519 

   520 5.3 The desc element

   521 --------------------

   522 

   523 The desc element can be used for description or documentation for any element. The data can be defined either as the content of the element or using xl:href attribute.

   524 

   525 .. list-table::

   526 

   527    - - Attributes name

   528      - Type

   529      - Default

   530      - Description

   531    - - CommonAttrs

   532      - 

   533      - 

   534      - Common attribute definitions defined in Common definitions

   535    - - xl:href

   536      - URI

   537      - not defined

   538      - Used to define the location of external description or documentation.

   539        From XLink [5].  

   540    - - xl:title

   541      - CDATA

   542      - not defined

   543      - Used to define title for the link defined using xl:href.

   544        From XLink [5].

   545 

   546 Example::

   547 

   548   <group id="cameragroup">

   549    <desc xl:href="file:howtoconfigurecamera.html" xl:title="Help"/>

   550   </group>

   551   <group id="someothergroup">

   552    <desc>Configure the camera</desc> 

   553   </group>

   554 

   555 5.4 The icon element

   556 --------------------

   557 

   558 The icon element can be used to define graphical icon for an element.

   559 

   560 .. list-table::

   561 

   562    - - Attributes name

   563      - Type

   564      - Default

   565      - Description

   566    - - CommonAttrs

   567      - 

   568      - 

   569      - Common attribute definitions defined in Common definitions

   570    - - xl:href*

   571      - URI

   572      - not defined

   573      - Used to define the location of the icon.

   574        From XLink [5].  

   575    - - xl:title

   576      - CDATA

   577      - not defined

   578      - Used to define title for the link defined using xl:href.

   579        From XLink [5].

   580 

   581 Example::

   582 

   583   <group id="cameragroup">

   584    <icon xl:href="file:camera.svg" xl:title="icon"/>

   585   </group>

   586 

   587 5.5 The link element

   588 --------------------

   589 

   590 The link element can be used to locate any external resource.

   591 

   592 .. list-table::

   593 

   594    - - Attributes name

   595      - Type

   596      - Default

   597      - Description

   598    - - CommonAttrs

   599      - 

   600      - 

   601      - Common attribute definitions defined in Common definitions

   602    - - xl:href*

   603      - URI

   604      - not defined

   605      - Used to define the location of the resource.

   606        From XLink [5].  

   607    - - xl:title

   608      - CDATA

   609      - not defined

   610      - Used to define title for the link defined using xl:href.

   611        From XLink [5].

   612 

   613 Example::

   614 

   615   <group id="cameragroup">

   616    <link xl:href="http://coolcameras.html" xl:title="camera shop"/>

   617   </group>

   618 

   619 ===================

   620 6. Configuration

   621 ===================

   622 

   623 The Configuration ML is used define the configuration elements and values for them. The root element of the document is configuration element.

   624 

   625 The elements and attributes included in this module are:

   626 

   627 .. list-table::

   628 

   629    - - Elements

   630      - Attributes

   631      - Content Model

   632    - - configuration

   633      - CommonAttrs, xmlns (URI = " http://www.s60.com/xml/confml/2"), version (NMTOKEN = "1.0"), name (xs:token)

   634      - meta?; desc*; icon*; link*; xi:include*; feature*; view*; configuration*; data?; rfs?

   635    - - `feature <#_The_header_element>`_

   636      - CommonAttrs, name (xs:token), ref* (XPATH), relevant (xs:token)

   637      - desc*; icon*; link*; setting*

   638    - - `setting <#_The_include_element>`_

   639      - CommonAttrs, relevant (xs:token), required (NMTOKEN), constraint (xs:token), readOnly (NMTOKEN), name (xs:token), type* (NMTOKEN), ref* (XPATH), minOccurs (NUMBER), maxOccurs (NMTOKEN), mapKey (XPATH), mapValue (XPATH)

   640      -  desc*; icon*; link*; option*; setting*; xs:minInclusive?; xs:maxInclusive?; (line-break) xs:minExclusive?; xs:maxExclusive?; xs:pattern*; xs:minLength?; maxLength?; totalDigits?; property*; localPath*; targetPath*)

   641    - - localPath

   642      - CommonAttrs, constraint (xs:token), readOnly (NMTOKEN), required (NMTOKEN), map (XPATH)

   643      - desc*; icon*; link*

   644    - - targetPath

   645      - CommonAttrs, constraint (xs:token), readOnly (NMTOKEN), required (NMTOKEN), map (XPATH)

   646      - desc*; icon*; link*

   647    - - `option <#_The_views_element>`_

   648      - CommonAttrs, name* (xs:token), value* (CDATA), relevant (xs:token), map (XPATH)

   649      - desc*; icon*; link*

   650    - - `property <#_The_property_element>`_

   651      - CommonAttrs, name (xs:token), value (CDATA), unit (xs:token)

   652      - desc*; icon*; link*

   653    - - `view <#_The_view_element_1>`_

   654      - CommonAttrs, name* (xs:token)

   655      - meta?; desc*; icon*; link*; group*

   656    - - `group <#_The_group_element>`_

   657      - CommonAttrs, name* (xs:token)

   658      - group*; desc*; icon*; link*; setting*

   659    - - xs:minInclusive 

   660      - value (NUMBER)

   661      - EMPTY

   662    - - xs:maxInclusive

   663      - value (NUMBER)

   664      - EMPTY

   665    - - xs:minExclusive 

   666      - value (NUMBER)

   667      - EMPTY

   668    - - xs:maxExclusive

   669      - value (NUMBER)

   670      - EMPTY

   671    - - xs:pattern

   672      - value (xs:token)

   673      - EMPTY

   674    - - xs:length

   675      - value (NUMBER)

   676      - EMPTY

   677    - - xs:minLength

   678      - value (NUMBER)

   679      - EMPTY

   680    - - xs:maxLength

   681      - value (NUMBER)

   682      - EMPTY

   683    - - xs:totalDigits

   684      - value (NUMBER)

   685      - EMPTY

   686    - - `data <#_The_data_element>`_

   687      - CommonAttrs

   688      - ANY

   689    - - `rfs <#_The_rfs_element>`_

   690      - CommonAttrs

   691      - ANY

   692 

   693 All restriction elements (known as facets) starting with xs namespace prefix are defined in XML Schema [7]. Only listed attributes are supported for those elements. The rest of the elements are defined in the following sections.

   694 

   695 6.1 The configuration element

   696 -----------------------------

   697 

   698 The configuration element is the root element of Configuration ML document. Version of the used specification must be defined using version attribute.

   699 

   700 Typically first child element under configuration is meta element. After that feature, view, and data elements follow.

   701 

   702 .. list-table::

   703 

   704    - - Attributes name

   705      - Type

   706      - Default

   707      - Description

   708    - - CommonAttrs

   709      - 

   710      - 

   711      - Common attribute definitions defined in Common definitions.

   712    - - version*

   713      - NMTOKEN

   714      - not defined

   715      - The version of the document. This attribute is mandatory and its value must be "1.0".

   716    - - name

   717      - xs:token

   718      - not defined

   719      - Textual name of the configuration. 

   720 

   721 Example::

   722 

   723   <?xml version="1.0"?>

   724   <configuration xmlns="http://www.s60.com/xml/confml/2" version="1.0" name="myfirstconfiguration">

   725    <meta/>

   726    <feature/>

   727    <data/>

   728    <rfs/>

   729   </configuration>

   730 

   731 6.2 The feature element

   732 -----------------------

   733 

   734 The feature element defines one or more configuration elements in terms of settings. Feature element is used to group settings into logical collections. A configuration ML feature typically maps into a feature of a subsystem, a platform or a product.

   735 

   736 .. list-table::

   737 

   738    - - Attributes name

   739      - Type

   740      - Default

   741      - Description

   742    - - CommonAttrs

   743      - 

   744      - 

   745      - Common attribute definitions defined in Common definitions.

   746    - - name

   747      - xs:token

   748      - not defined

   749      - Textual name of the feature.

   750    - - ref*

   751      - XPATH (path)

   752      - not defined

   753      - Uniquely identifies the feature in the configuration.

   754        A path to the feature specific element containing values for all the setting. The path must be defined using )relative location path in abbreviated XPATH [6] form. The path must map to at most one feature element.

   755        Together with ref element of a setting, the path must be relative location path to a setting specific element in abbreviated XPATH [6] form.  

   756        The ref attribute of the feature is also used for identifying settings inside view definitions.

   757        This attribute is mandatory for all features.

   758    - - relevant

   759      - xs:token

   760      - true

   761      - Defines whether the feature is used. Can be used to exclude all the settings of the feature that are not relevant in some context. Values with this property value false for the parent feature are not used.

   762        The grammar of expression language is defined in chapter 8.

   763 

   764 Example::

   765 

   766   <feature id="f_camf_00" name="Camcorder Features" ref="CamcorderFeatures">

   767    <desc/>

   768    <setting/>

   769    <setting/>

   770   </feature>

   771 

   772 6.3 The setting element

   773 -----------------------

   774 

   775 The setting element defines a single configurable setting. When used inside a view element, setting element is used to include the setting in a view, and possibly redefine any of its properties.

   776 

   777 Sequential settings are defined using hierarchical settings definitions where setting element contains one or more setting definitions. The settings of each item in a sequence are defined using sequence elements under the setting element. The number of settings in a sequence can be limited with minOccurs and maxOccurs attributes.

   778 

   779 .. list-table::

   780 

   781    - - Attributes name

   782      - Type

   783      - Default

   784      - Description

   785    - - CommonAttrs

   786      - 

   787      - 

   788      - Common attribute definitions defined in Common definitions.

   789    - - name

   790      - xs:token

   791      - ""

   792      - Textual name of the setting. To be used in user interfaces of tools and documentation.

   793    - - type*

   794      - NMTOKEN

   795      - not defined

   796      - Type of the element. Refer to chapter 7 for supported types. Attribute is not allowed when element is inside a view.

   797    - - ref*

   798      - XPATH (path)

   799      - not defined

   800      - Uniquely identifies the setting under the parent feature. A path to the element containing value for the setting. The path must be defined using relative location path in abbreviated XPATH [6] form. The path must map to at most one value element. The ref attribute is also used for uniquely identifying settings inside view definitions and in setting implementation. Because of this ref of a setting must be unique under the feature. This attribute is mandatory for all settings under a feature element. Attribute is not allowed when element is inside a view.

   801    - - constraint

   802      - xs:token

   803      - true

   804      - Defines any constrains for the values supported by the setting. Values with this property evaluating to false are invalid. The grammar of expression language is defined in chapter 8.

   805    - - relevant

   806      - xs:token

   807      - true

   808      - Defines whether the setting is used. Can be used to exclude settings that are not relevant in some context. Values with this property evaluating to false are not used. The grammar of expression language is defined in chapter 8.

   809    - - readOnly

   810      - NMTOKEN

   811      - false

   812      - Defines the settings as non-modifiable. Values to settings with this attribute value true are restricted from being defined outside the configuration where they where originally defined in. Therefore only the initial default values can be defined for read only settings. The supported values are true and false.

   813    - - required

   814      - NMTOKEN

   815      - false

   816      - Defines whether a value must be defined for the settings before the configuration is complete. Can be used to force user to define a value for settings that can not use any default value. Missing required value must not prevent saving configuration at any point. In case defined for a setting of type sequence, requiredness mandates having at least one item-setting defined. In case defined for a sub-setting of a sequence, requiredness is evaluated separately for each item-setting. The supported values are true and false. The use of requiredness information is tool specific. Completeness of a configuration might be required by a configuration tool in case of validation or generation of a variant. 

   817    - - minOccurs

   818      - NUMBER

   819      - 0

   820      - The minimum number of value elements allowed in case of sequence type of setting.

   821    - - maxOccurs

   822      - NMTOKEN

   823      - "unbounded"

   824      -  The maximum number of value elements allowed in case of sequence type of setting. When any number of elements are allow, value "unbounded" can be used.

   825    - - mapKey

   826      - XPATH (path)

   827      - not defined

   828      - In case setting is used as enumeration source for name-id mapping (see chapter 6.11), value of this attribute defines the key part of the enumeration. If used, setting's type must be sequence. All the values residing in the attribute must be unique within the sequence.

   829    - - mapValue

   830      - XPATH (path)

   831      - not defined

   832      - In case setting is used as enumeration source for name-id mapping (see chapter 6.11), value of this attribute defines the value part of the enumeration. If used, setting's type must be sequence.

   833 

   834 Example::

   835 

   836   <setting constraint=". &gt; '1'" name="Audio Codec" type="Selection" ref="AudioCodec">

   837    <desc/>

   838    <option/>

   839    <option/>

   840   </setting>

   841   <setting id="bookmarks" type="sequence" maxOccurs="50" ref="Bookmark">

   842     <setting id="bookmark_name" name="Name" required="true" type="string" ref="Name">

   843      <xs:maxLength value="50"/>

   844     </setting>

   845     <setting id="bookmark_serveradd" name="Server Address" required="true" type="string" ref="ServerAddress">

   846      <xs:maxLength value="250"/>

   847     </setting>

   848   </setting>

   849 

   850 6.4 The file and folder elements

   851 --------------------------------

   852 

   853 The file and folder elements define the copying rules of files and folders. Both elements consist of sub-settings called localPath and targetPath. The following attributes are applicable for both of these sub-settings. For more detailed explanation along with the examples, see chapter 7.5.

   854 

   855 .. list-table::

   856 

   857    - - Attributes name

   858      - Type

   859      - Default

   860      - Description

   861    - - CommonAttrs

   862      - 

   863      - 

   864      - Common attribute definitions defined in Common definitions.

   865    - - constraint

   866      - xs:token

   867      - true

   868      - Defines any constrains for the values supported by the path definition.  Values with this property evaluating to false are invalid. The grammar of expression language is defined in chapter 8.

   869    - - readOnly

   870      - NMTOKEN

   871      - false

   872      - Defines the path as non-modifiable. Values to paths with this attribute value true are restricted from being defined outside the configuration where they where originally defined in. Therefore only the initial default values can be defined for read only settings. The supported values are true and false.

   873    - - required

   874      - NMTOKEN

   875      - false

   876      - Defines whether a value must be defined for the path before the configuration is complete. Can be used to force user to define a value for path that can not use any default value. Missing required value must not prevent saving configuration at any point. The supported values are true and false. The use of requiredness information is tool specific. Completeness of a configuration might be required by a configuration tool in case of validation or generation of a variant.

   877    - - map

   878      - XPATH (path)

   879      - not defined

   880      - In case path definition uses symbolic paths which require resolving, the map attribute defines the xpath to sequence that contains this mapping information. See (bookmark-ref (@ (reference-format chapter) (ref-name _Ref210621287)) 7.5) for more elaborate description.

   881 

   882 6.5 The option element

   883 ----------------------

   884 

   885 The option element defines pre-defined named value for a setting. The value stored in the data is defined using value attribute. It can be used with any type of setting but when used for a selection or multiSelection, only the values defined using option element are allowed. In case of other types, not all allowed values need to be pre-defined making it possible to support for example free form input in addition to mostly used values. The values defined by option element must be valid values for the setting; options with non-valid values (also taking account the additional restrictions defined in a view) are not allowed.

   886 

   887 When used inside a view element, option element is used to add or redefine any of the options.  

   888 

   889 .. list-table::

   890 

   891    - - Attributes name

   892      - Type

   893      - Default

   894      - Description

   895    - - CommonAttrs

   896      - 

   897      - 

   898      - Common attribute definitions defined in Common definitions. 

   899    - - name*

   900      - xs:token

   901      - not defined

   902      - Optional descriptive name for the value. Can be used in tools instead of the value itself.

   903    - - value*

   904      - CDATA

   905      - not defined

   906      - The value of the option as used in elements under data element. Note that this value and the implementation specific value used at runtime are not necessarily the same.

   907    - - relevant

   908      - xs:token

   909      - true()

   910      - Defines whether the option is valid. Can be used to exclude options that are not relevant in some context. Options with this property evaluating to false are not applicable for the setting. The grammar of expression language is defined in chapter 8.

   911    - - map

   912      - XPATH (path)

   913      - not defined

   914      - Can be used in case the setting where option resides uses name-id mapping (see chapter 6.11). Value of this attribute defines the path to the setting, where from values and names are fetched. Note that referred setting must be of type sequence.

   915 

   916 Example::

   917 

   918   <setting name="MMS Message Size" type="Int" ref="MMSMessageSize">

   919    <option name="small" value="0"><desc/></option>

   920    <option name="medium" value="2" relevant="MMSMedium = true"/>

   921    <xs:minInclusive value="0"/>

   922    <xs:maxInclusive value="10"/>

   923   </setting>

   924 

   925 6.6 The property element

   926 ------------------------

   927 

   928 The property element defines additional properties for settings. Property elements can be used for example to define additional constraints for settings that are not expressible using other attributes. The use of properties is application specific.  

   929 

   930 Refer to chapter 9 for recommended names of commonly used properties.

   931 

   932 .. list-table::

   933 

   934    - - Attributes name

   935      - Type

   936      - Default

   937      - Description

   938    - - CommonAttrs

   939      - 

   940      - 

   941      - Common attribute definitions defined in Common definitions.

   942    - - name*

   943      - xs:token

   944      - Not defined

   945      - Identifier of the property.

   946    - - value*

   947      - CDATA

   948      - Not defined

   949      - The value of the property.

   950    - - unit

   951      - xs:token

   952      - As defined for the property

   953      - The unit of the value.

   954 

   955 Example::

   956 

   957   <setting>

   958    <property name="mime" value="image/svgt image/bmp"/>

   959    <property name="resolution" value="100x100"/>

   960    <property name="maxSize" value="100" unit="kB"/>

   961 

   962 6.7 The view element

   963 --------------------

   964 

   965 The view element defines a subset of settings under one or more group elements. Views can therefore be used to group needed elements for easy visualization and manipulation. The view elements are defined directly under configuration element.

   966 

   967 Any number of views can be defined in a configuration, but typically only one of them can be then activated at time by the application using configuration.

   968 

   969 The view is defined using one or more groups. Settings in views are always defined inside a group. A setting can exist only once in a single view. All the settings referred there must have been previously defined using feature and setting elements. All the data elements and their values in the configuration still exist, and should be validated and used, even though they could be hidden from the active view. Because of this, tools might optionally still visualize values that are invalid, but are not part of the active view. Refer to chapter 3.5 for more information about use of views.

   970 

   971 

   972 .. list-table::

   973 

   974    - - Attributes name

   975      - Type

   976      - Default

   977      - Description

   978    - - CommonAttrs

   979      - 

   980      - 

   981      - Common attribute definitions defined in Common definitions. 

   982    - - name*

   983      - xs:token

   984      - not defined

   985      - The name of the view.

   986 

   987 Example::

   988 

   989   <view name="Isetta View">

   990    <desc/>

   991    <group/>

   992    <group/>

   993   </view>

   994 

   995 6.8 The group element

   996 ---------------------

   997 

   998 The group element (re-)defines the logical grouping of settings inside a view. When view is not used, the settings are clustered according to features they are defined in. Group elements therefore can be used to create virtual features with settings selected from one or more features.

   999 

  1000 Settings included in group are identified using ref attribute of the setting. Please notice that ref of the setting can refer only to one setting.

  1001 

  1002 Groups can contain groups for creating hierarchical grouping. It is not possible to directly use features as grouping elements in group hierarchy; views always contain only groups and/or settings.

  1003 

  1004 .. list-table::

  1005 

  1006    - - Attributes name

  1007      - Type

  1008      - Default

  1009      - Description

  1010    - - CommonAttrs

  1011      - 

  1012      - 

  1013      - Common attribute definitions defined in Common definitions. 

  1014    - - name*

  1015      - xs:token

  1016      - not defined

  1017      - Textual name of the group.

  1018 

  1019 Example::

  1020 

  1021   <group name="Common Settings">

  1022    <desc>A group description</desc>

  1023    <setting ref="CamcorderFeatures/MMSMessageSize" name="MMS Message Size" type="Int">

  1024     <option name="small" value="1"/> <!-- was zero -->

  1025     <option name="medium" value="2"/>

  1026     <option name="large" value="4"/> <!-- added -->

  1027     <xs:minInclusive value="0"/>

  1028     <xs:maxInclusive value="9"/> <!-- was 10 -->

  1029     <desc>A better description added here</desc>

  1030    </setting>

  1031    <group>

  1032     <setting ref="OtherFeatures/*"/> <!-- selects all the settings of the feature -->

  1033    <group>

  1034   </group>

  1035    <setting ref="CamcorderFeatures/othersetting"/>

  1036   </group>

  1037   </group>

  1038 

  1039 6.9 The data element

  1040 --------------------

  1041 

  1042 The data defines the values of the configuration. Only one data element is allowed directly under a configuration element, but because of the hierarchical nature of configurations, there can be several data elements in a configuration. Values under data element can be for example product or operator specific, or they can be even default values defined by the owner of the feature.

  1043 

  1044 Following attributes are supported for all descendant elements of the data element.

  1045 

  1046 .. list-table::

  1047 

  1048    - - Attributes name

  1049      - Type

  1050      - Default

  1051      - Description

  1052    - - CommonAttrs

  1053      - 

  1054      - 

  1055      - Common attribute definitions defined in Common definitions. 

  1056 

  1057 The following attributes are supported for all descendant elements of data element that define data for sequence settings only. These attributes can be defined only for item-setting level elements and not for sub-setting level elements.

  1058 

  1059 .. list-table::

  1060 

  1061    - - Attributes name

  1062      - Type

  1063      - Default

  1064      - Description

  1065    - - extensionPolicy

  1066      - NMTOKEN

  1067      - "replace"

  1068      - Defines whether the setting replaces or extends the previously defined data of the sequence setting. Extension allows incremental definition of sequence item-settings in multiple configurations. This attribute can be defined only for the first item-setting. Same extension policy is automatically applied to all other defined item-settings of the same setting in that configuration. The valid values are: replace (default), append and prefix. By default (extensionPolicy="replace") the data defined completely replaces all the items that where previously defined in any included configuration according to priority rules defined in chapter 3.4.1. When this attribute has value "append" the defined sequence items are interpreted to be added to the end of the previously defined items. When this attribute has value "prefix" the defined sequence items are interpreted to be added to the front of the previously defined items. In both cases with append and prefix, any changes made to data in an included configuration will therefore be automatically included as part of the settings data. Refer to chapter 7.6 for full explanation of sequence templates.

  1069    - - template

  1070      - NMTOKEN

  1071      - false

  1072      - Marks sequence item-setting to be a sequence template instead. If template has value true , then the values of the sub-settings are not used as item-settings. Setting templates can be defined for a setting only in the same configuration that defined the setting. There can be at zero or one template per each setting. Refer to chapter 7.6 for full explanation of sequence templates.

  1073 

  1074 The following attributes are supported for data elements, which define data for name-id mapping cases (see chapter 6.11).

  1075 

  1076 .. list-table::

  1077 

  1078    - - Attributes name

  1079      - Type

  1080      - Default

  1081      - Description

  1082    - - map

  1083      - XPATH

  1084      - not defined

  1085      - Defines the xpath to a setting used for name-id mapping.

  1086 

  1087 The names of descendant elements of data element are feature-specific. The name of the element is defined using the ref attribute of the feature. Under these feature specific elements there are one or more setting specific elements each of them defining a value for a setting. The name of these elements under one feature is defined using the ref attribute of the setting.

  1088 

  1089 See chapter 7 for setting type specific data examples.

  1090 

  1091 6.10 The rfs element

  1092 --------------------

  1093 

  1094 The data defines the Restore Factory Setting (RFS) policies of the settings. RFS policy for a setting is defined under feature and setting specific elements, as defined using ref attributes of the feature and setting in question.  

  1095 

  1096 Only one rfs element is allowed directly under a configuration element, but because of the hierarchical nature of configurations, there can be several rfs elements in a configuration. Values under rfs element can be for example product or operator specific or they can be default values defined by the owner of the feature. The RFS policy values are always of Boolean type. By default no settings are restored in RFS. In case there are multiple settings that are stored into a single restorable entity such a Central Repository key, then the whole entity is restored always in case there even one of the settings have RFS enabled.

  1097 

  1098 Following attributes are supported for all descendant elements of data element.

  1099 

  1100 .. list-table::

  1101 

  1102    - - Attributes name

  1103      - Type

  1104      - Default

  1105      - Description

  1106    - - CommonAttrs

  1107      - 

  1108      - 

  1109      - Common attribute definitions defined in Common definitions. 

  1110 

  1111 Example::

  1112 

  1113   <configuration>

  1114    <rfs>

  1115     <MyFeature>

  1116      <MySetting>true</MySetting>

  1117      <MyOtherSetting>true</MyOtherSetting>

  1118     </MyFeature>

  1119     <MyOtherFeature>

  1120      <MyBooleanSetting>true</MyBooleanSetting> <!-- can cause also other Boolean settings

  1121        to be restored in case they are all stored into single Central Repository key -->

  1122     </MyOtherFeature>

  1123    </rfs>

  1124   </configuration>

  1125 

  1126 6.11 Name-Id mapping for setting elements

  1127 -----------------------------------------

  1128 

  1129 In some cases, dynamically created name-id sequences act as enumeration values for other settings. As an example, one of the configurations define a setting for listing available device access points. Each access point has identifier, name and some other attributes. Other configurations use these definitions in their own settings, so that one of these predefined access points can be selected (e.g. device default access point). The mechanism to do this is explained in this chapter.

  1130 

  1131 At first, setting used as name-id mapping source is defined. This setting must be type of sequence, and it must have attributes mapKey and mapValue. Attribute mapKey defines the mapping key for a subsettings, while mapValue defines the value part. Example of this is seen below (both the feature definition and related data)::

  1132 

  1133   <feature name="Connectivity Settings" ref="ConnectivitySettings">

  1134    <setting type="sequence" maxOccurs="10" mapKey="APID" mapValue="APName" name="Device Accesspoints" ref="DeviceAccesspoint"> 

  1135     <setting name="Name" ref="APName" type="string" required="true" />