Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 238 insertions, 0 deletions

diff --git a/offapi/com/sun/star/configuration/ConfigurationProvider.idl b/offapi/com/sun/star/configuration/ConfigurationProvider.idl
new file mode 100644
index 000000000..ff337bda2
--- /dev/null
+++ b/offapi/com/sun/star/configuration/ConfigurationProvider.idl
@@ -0,0 +1,238 @@
+/* -*- 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_ConfigurationProvider_idl__
+#define __com_sun_star_configuration_ConfigurationProvider_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 and serves as a
+ factory for objects that provide access to a subset of the configuration.
+
+ <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. Arguments must be provided as
+ com::sun::star::beans::NamedValue
+ or com::sun::star::beans::PropertyValue.
+ If the parameters given are incomplete missing values are taken
+ from the context or the environment. If an instance already exists for the
+ given set of arguments, the existing instance may be reused.
+ In particular, instantiating a provider without explicit arguments to access
+ the default configuration data will always yield the same
+ com::sun::star::configuration::DefaultProvider object.
+ </p>
+ <p>Some arguments for
+ com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments()
+ may be given default values during creation of this service. In particular
+ this applies to the parameters <code>"Locale"</code> and <code>"EnableAsync"</code>.
+ </p>
+
+ @deprecated Use theDefaultProvider instead.
+ */
+published service ConfigurationProvider
+{
+/** 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 view of the 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.
+ </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.
+ </p>
+
+ <p>Other arguments can be used to control the behavior of the view. These
+ are different for different implementations. Whether and how they are used
+ may also depend on the configuration store and configuration that were
+ selected when the provider was created.
+ </p>
+
+ <p>An implementation must ignore unknown arguments.</p>
+
+ <p>Some parameters that are commonly supported are:</p>
+
+ <ul>
+    <li>
+       <strong>Selecting data into a view:</strong>
+       <dl>
+         <dt><code>"nodepath"</code> : `string`</dt>
+         <dd>specifies the location of the view root in the configuration.</dd>
+         <dt><code>"depth"</code> : `short`</dt>
+         <dd>specifies that elements of the hierarchy that are more than the given
+          number of nesting levels away from the root need not be included in the
+          view.
+         </dd>
+         <dt><code>"locale"</code> : com::sun::star::lang::Locale</dt>
+         <dd>specifies the locale for which localized values should be
+          retrieved.
+         </dd>
+       </dl>
+
+       <p><strong>Example:</strong> In the hierarchy
+<BR /><pre>
+ A - B1 - C1
+   |
+   - B2 - C2 (localized: de, en, fr, ..)
+   |    |
+   |    - C3 - D1
+   |    |    |
+   |    |    - D2 - E1
+   |    |
+   |    - C4 - D3 - E2 - F1
+   |    |              |
+   |    |              - F2
+   |    |
+   |    - C5
+   |
+   - B3
+   |
+   - B4 - C6 - D4 - E3
+
+</pre>
+         <BR />selecting a view with <code>nodepath = "/A/B2"</code>,
+         <code>depth = 2</code> and <code>locale = &lt;Locale for en_US&gt;</code>
+         would result in the tree fragment
+<BR /><pre>
+(A-) B2 - C2 (en)
+        |
+        - C3 - D1
+        |    |
+        |    - D2 (..)
+        |
+        - C4 - D3 (..)
+        |
+        - C5
+
+</pre>
+       </p>
+    </li>
+
+    <li>
+       <strong>Controlling cache behavior:</strong> (with providers that
+        cache configuration data)
+       <dl>
+         <dt><code>"enableasync"</code> : `boolean`</dt>
+         <dd>controls how updates are handled in the cache. If `TRUE`, the
+          cache may operate in <em>write-back</em> mode, where updates at
+          first only affect the cache and are written to persistent storage
+          at some later time. If `FALSE`, the cache must operate in
+          <em>write-through</em> mode, where updates are written to persistent
+          storage at once - that is before
+          com::sun::star::util::XChangesBatch::commitChanges()
+          returns.
+          <p><em>This parameter was formerly called <code>"lazywrite"</code>.
+            The old name should still be supported for compatibility.
+          </em></p>
+         </dd>
+
+         <dt><code>"nocache"</code> : `boolean`</dt>
+         <dd>This deprecated parameter
+          specifies that data for the view is not taken from the cache, but
+          read directly from storage. This may entail that future changes that
+          become visible in the cache are not reflected in this view and that
+          changes done through this view are not reflected in the cache.
+          <BR /><strong>Use with caution !</strong>
+          <p><em>This parameter is not supported by all implementations and may be
+          silently ignored !
+          </em></p>
+         </dd>
+       </dl>
+    </li>
+ </ul>
+
+ <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().
+ Note that the default provider is owned by the
+ com::sun::star::lang::ServiceManager and should not be
+ disposed of by user code.
+ </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: */