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