1/************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23#ifndef __com_sun_star_configuration_ConfigurationProvider_idl__ 24#define __com_sun_star_configuration_ConfigurationProvider_idl__ 25 26#ifndef __com_sun_star_lang_XMultiServiceFactory_idl__ 27#include <com/sun/star/lang/XMultiServiceFactory.idl> 28#endif 29 30#ifndef __com_sun_star_lang_XComponent_idl__ 31#include <com/sun/star/lang/XComponent.idl> 32#endif 33 34//============================================================================= 35 36module com { module sun { module star { module configuration { 37 38//============================================================================= 39/** manages one, or more, complete sets of configuration data for 40 administrative puposes and serves as a factory for objects that 41 provide access to subsets of these shared configurations. 42 43 <p>Shared sets of configuration data usually serve to provide defaults, 44 which are used if no individual settings are present. Depending on the data 45 store multiple layers of defaults may be combined with a user-specific layer 46 to make up the final configuration. 47 </p> 48 <p>Many aspects of the supported behavior depend strongly on the underlying 49 data store and on the administrative structures it defines. With some data 50 stores this service also enables access to individual users' configuration 51 data by an administrator. 52 </p> 53 <p>On the other hand, in the simplest model there is only a single layer of 54 default data which is accessible through this service. 55 </p> 56 <p>An implementation is usually obtained from a 57 <type scope="com::sun::star::lang">ServiceManager</type>. The arguments passed to 58 <member scope="com::sun::star::lang">XMultiComponentFactory::createInstanceWithContextAndArguments()</member> 59 select the configuration data source. They may also define the scope of 60 administrable data or contain credentials to be used to authorize the 61 administrative access. Missing parameters may be filled in 62 from the context or the environment. 63 </p> 64 65 @see com::sun::star::configuration::ConfigurationProvider 66 Offers the same services and creates the same accessor objects as this 67 service, but accesses the personal configuration. 68 69 <p>A <type> ConfigurationProvider</type> provides access to the personal 70 layer of configuration data of the current user context. It should in 71 most cases be used when <em>using</em> the configuration data, although 72 for most contexts a <type>AdministrationProvider</type> can be used as 73 a drop-in replacement. 74 </p> 75 */ 76published service AdministrationProvider 77{ 78/** allows creating access objects for specific views such as subsets and fragments 79 of the configuration. 80 81 <p>The parameter <var>aServiceSpecifier</var> passed to 82 <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member> 83 supports at least the service specifiers 84 <code>"com.sun.star.configuration.ConfigurationAccess"</code> and 85 <code>"com.sun.star.configuration.ConfigurationUpdateAccess"</code>. 86 </p> 87 88 <p>Using the first of these service specifiers requests a read-only view of 89 the configuration. 90 The object that is created implements service <type>ConfigurationAccess</type>. 91 To reflect its <em>element role</em> as root of the view, it implements 92 service <type>AccessRootElement</type>. 93 </p> 94 95 <p>Using the second form requests an updatable view of the configuration. 96 The object that is created should implement service 97 <type>ConfigurationUpdateAccess</type>. To reflect its <em>element role</em> 98 which includes controlling updates for the whole view, it implements 99 service <type>UpdateRootElement</type>. 100 <BR />If the root element of the view is marked read-only (as indicated 101 by <const scope="com::sun::star::beans">PropertyAttributes::READONLY</const>), 102 the implementation may either raise an exception or return a (read-only) 103 <type>ConfigurationAccess</type>/<type>AccessRootElement</type> instead. 104 </p> 105 106 <p>The arguments passed to 107 <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member> 108 in parameter <var>aArguments</var> specify the administrative entity for which 109 data should be administered. In other words they determine the layer to which 110 changes will apply. They also specify the view of that configuration that 111 should be created. That is, they determine the subset of elements that can be 112 accessed starting from the returned object. Each element of the argument 113 sequence should be a <type scope="com::sun::star::beans">PropertyValue</type> 114 or a <type scope="com::sun::star::beans">NamedValue</type>, 115 so that the parameters can be identified by name rather than by position. 116 </p> 117 118 <p>What combinations of arguments are supported depends on the service name 119 and on the data store being administered. 120 </p> 121 122 <p>With both of the standard service-specifiers above, an implementation must 123 accept a single argument named <code>nodepath</code> of type <atom>string</atom>. 124 This argument must contain the absolute path to an element of the 125 configuration. The view that is selected consists of the named element and 126 all its descendants. The administrative entity is the default for the 127 <type>AdministrationProvider</type>. Usually this is the largest entity 128 encompassing all entities accessible from this instance. In other words this 129 can be used to influence as global a scope as possible. 130 </p> 131 132 <p>Other arguments can be used to select a more specific entity and to control 133 the behavior of the view. These are different for different implementations 134 and data stores. Whether and how they are used may also depend on properties 135 that were selected when the provider was created. 136 </p> 137 138 <p>An implementation may ignore unknown arguments.</p> 139 140 <p>Some parameters that are commonly supported are described for service 141 <type>ConfigurationProvider</type>. 142 </p> 143 <p>One notable difference exists for parameter <code>"Locale"</code>. For a 144 <type>ConfigurationProvider</type> the default behavior usually is to select 145 the locale set up for the user. But this service by default gets data for all 146 locales for which data is present. Locale-dependent values in this case are 147 replaced by a <type>SetAccess</type> using the language names as accessors. 148 This also allows targeted setting of values for selected locales. 149 This behavior can be requested explicitly by specifing a special argument 150 value <code>locale = "*"</code>. 151 </p> 152 153 <p><member scope="com::sun::star::lang">XMultiServiceFactory::createInstance()</member> 154 may be unusable. Only an implementation that supports service names that can be 155 used with no further arguments support this method. It should return the 156 same result as if 157 <member scope="com::sun::star::lang">XMultiServiceFactory::createInstanceWithArguments()</member> 158 had been called using an empty sequence of arguments. 159 </p> 160*/ 161 interface com::sun::star::lang::XMultiServiceFactory; 162 163 164/** allows controlling or observing the lifetime of the configuration. 165 166 <p>The owner of the provider may dispose of this object 167 using <member scope="com::sun::star::lang">XComponent::dispose()</member>. 168 </p> 169 170 <p>Views created by the provider generally refer to data that is managed by 171 the provider. Therefore, disposing of the provider will cause all objects 172 belonging to these views to be disposed of as well. This does not apply to 173 <em>snapshot</em> views that have their own copy of the data, if available. 174 </p> 175 176*/ 177 interface com::sun::star::lang::XComponent; 178 179}; 180 181//============================================================================= 182 183}; }; }; }; 184 185#endif 186 187 188