diff options
Diffstat (limited to 'offapi/com/sun/star/configuration/ConfigurationAccess.idl')
| -rw-r--r-- | offapi/com/sun/star/configuration/ConfigurationAccess.idl | 235 |
1 files changed, 235 insertions, 0 deletions
diff --git a/offapi/com/sun/star/configuration/ConfigurationAccess.idl b/offapi/com/sun/star/configuration/ConfigurationAccess.idl new file mode 100644 index 000000000..9e34f9adf --- /dev/null +++ b/offapi/com/sun/star/configuration/ConfigurationAccess.idl @@ -0,0 +1,235 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ +#ifndef __com_sun_star_configuration_ConfigurationAccess_idl__ +#define __com_sun_star_configuration_ConfigurationAccess_idl__ + +#include <com/sun/star/configuration/HierarchyAccess.idl> +#include <com/sun/star/configuration/HierarchyElement.idl> +#include <com/sun/star/configuration/SetAccess.idl> +#include <com/sun/star/configuration/GroupAccess.idl> +#include <com/sun/star/configuration/AccessRootElement.idl> +#include <com/sun/star/configuration/SetElement.idl> +#include <com/sun/star/configuration/GroupElement.idl> + + +module com { module sun { module star { module configuration { + +/** provides read access to a fragment of the configuration hierarchy. + + <p>Values that are direct or indirect descendants of a root element can be + retrieved and, if themselves objects, navigated. Other interfaces provide + access to information about this element and its context. + Changes to values in the hierarchy can be monitored by event listeners. + </p> + + <p>Descendants of this service also implement this service. + </p> + + <p>Ultimately the configuration holds values. These values are organized into + a hierarchy using structural elements. The structure is defined in advance in + a schema. Necessary information from the schema is stored in the configuration + repository itself and is accessible through an implementation of this service. + </p> + + <p>Two different kinds of structural elements are used in the configuration + hierarchy: + </p> + <dl> + <dt>Sets</dt> + <dd>are dynamic containers of homogeneous elements. Which elements + a <em>set</em> contains can vary. Their names are defined by the + clients that insert them. On the other hand, the <em>type</em> of + the elements is the same for all elements. In the case of elements + that are themselves hierarchy objects, the <em>type</em> includes + the structure of the hierarchy fragment they contain. Such types + are defined in the configuration schema as <em>templates</em>. + </dd> + + <dt>Groups</dt> + <dd>are static collections of heterogeneous elements. The names and + types of the elements of a <em>group</em> are completely defined in the + configuration schema. Here each element may be of a different + <em>type</em>, allowing <em>groups</em> that contain a mix of + subobjects and simple values. + </dd> + </dl> + + <p>Objects in the configuration hierarchy, for example, implementations of this service, + can thus be classified in the following ways: + </p> + <ul> + <li><em>Container</em> role: + An object that can hold child elements as a <em>set</em> or a <em>group</em>. + </li> + <li><em>Element</em> role: + An object may be an element of a <em>set</em> or a <em>group</em> + or else it may be the root element. + </li> + </ul> + + <p>Several types of simple <em>values</em> can be used in the configuration. + In addition to the basic (scalar) types, sequences of the basic types are + supported. The basic types are: + </p> + + <ul> + <li><strong>string</strong> can hold a human-readable text. + <p>Values are represented as `string`.</p> + <p>Sequences are represented as `string[]`.</p> + <p>"<em>human-readable</em>" here excludes non-printing characters + except for CR, LF and TAB [Unicode code points 9,10,13]. + For binary data, use type <strong>binary</strong> instead.</p> + </li> + <li><strong>boolean</strong> can hold the values `TRUE` or `FALSE`. + <p>Values are represented as `boolean`. + <p>Sequences are represented as `boolean[]`.</p> + </li> + <li><strong>short</strong> can hold a 16-bit signed integer. + <p>Values are represented as `short`.</p> + <p>Sequences are represented as `short[]`.</p> + </li> + <li><strong>int</strong> can hold a 32-bit signed integer. + <p>Values are represented as `long`.</p> + <p>Sequences are represented as `long[]`.</p> + </li> + <li><strong>long</strong> can hold a 64-bit signed integer. + <p>Values are represented as `hyper`.</p> + <p>Sequences are represented as `hyper[]`.</p> + </li> + <li><strong>double</strong> can hold a floating point number. + <p>Values are represented as `double`.</p> + <p>Sequences are represented as `double[]`.</p> + </li> + <li><strong>binary</strong> can hold a sequence of octets. + <p>Values are represented as `byte[]`.</p> + <p>Sequences are represented as `byte[][]`.</p> + </li> + </ul> + + <p>Within templates an additional type <strong>any</strong> can occur. When + such a template is used to create a new SetElement, the type + of the element is initially reported as `any` (having no value). + When the value of such an element is first set, it will assume the type used. + </p> + + <p>If the schema marks a value as <em>nullable</em> (which is indicated by + attribute com::sun::star::beans::PropertyAttribute::MAYBEVOID ), + its contents may be `NULL`. + </p> + + <p>The configuration should support explicit access to default values + (implementing com::sun::star::beans::XPropertyState + and com::sun::star::beans::XPropertyWithState). + </p> + + @see ConfigurationProvider + Root instances of this service can be requested from a + ConfigurationProvider. + + @see ConfigurationUpdateAccess + an extended service that includes facilities for modifying + configuration data. +*/ +published service ConfigurationAccess +{ + /** provides interfaces to access child and descendent elements. + + <p>An implementation actually implements a specialization of this service, + which depends on its <em>Container</em> role. + </p> + + <p>Implementations shall implement exactly one of:</p> + <ul> + <li>SetAccess if this element is a <em>Set</em>.</li> + <li>GroupAccess if this element is a <em>Group</em>.</li> + </ul> + */ + service HierarchyAccess; + + /** provides interfaces to obtain information about this element and its + role and context in the hierarchy. + + <p>An implementation actually implements a specialization of this service, + which depends on its <em>Element</em> role. + </p> + + <p>Implementations shall implement exactly one of:</p> + <ul> + <li>AccessRootElement if this element is the + <em>Root</em> of the whole hierarchy. Objects that can be + created directly by a ConfigurationProvider + implement this service.</li> + <li>SetElement if this element may be contained in a + <em>Set</em>.</li> + <li>GroupElement if this element is a child of a + <em>Group</em>.</li> + </ul> + + */ + service HierarchyElement; + + /** specializes HierarchyAccess, if this element is a <em>Set</em>. + + <p>This is an alternative to GroupAccess. + </p> + */ + [optional] service SetAccess; + + /** specializes HierarchyAccess, + if this element is a <em>Group</em>. + <p>This is an alternative to SetAccess. + </p> + */ + [optional] service GroupAccess; + + /** specializes HierarchyElement, + if this element is the <em>Root</em> of the whole hierarchy. + <p>This is an alternative to SetElement + or GroupElement. + </p> + + @see ConfigurationProvider + Instances obtained from a ConfigurationProvider will + implement this version of HierarchyElement. + */ + [optional] service AccessRootElement; + + /** specializes HierarchyElement, + if this element may be contained in a <em>Set</em>. + <p>This is an alternative to AccessRootElement + or GroupElement. + </p> + */ + [optional] service SetElement; + + /** specializes HierarchyElement, + if this element is a child of a <em>Group</em>. + <p>This is an alternative to AccessRootElement + or SetElement. + </p> +*/ + [optional] service GroupElement; +}; + + +}; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |