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