LibreOffice LibreOffice 26.2 SDK API Reference

Exported Interfaces | List of all members
AdministrationProvider Service Referencepublished

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. More...

`import"AdministrationProvider.idl";`

Inheritance diagram for AdministrationProvider:

## Exported Interfaces
interface | com::sun::star::lang::XMultiServiceFactory
| allows creating access objects for specific views such as subsets and fragments of the configuration. More...
interface | com::sun::star::lang::XComponent
| allows controlling or observing the lifetime of the configuration. More...

## Additional Inherited Members
Public Member Functions inherited from XMultiServiceFactory
com::sun::star::uno::XInterface | createInstance ([in] string aServiceSpecifier) raises ( com::sun::star::uno::Exception )
| Creates an instance classified by the specified name. More...
com::sun::star::uno::XInterface | createInstanceWithArguments ([in] string ServiceSpecifier, [in] sequence< any > Arguments) raises ( com::sun::star::uno::Exception )
| Creates an instance classified by the specified name and passes the arguments to that instance. More...
sequence< string > | getAvailableServiceNames ()
| Provides the available names of the factory to be used to create instances. More...
Public Member Functions inherited from XInterface
any | queryInterface ([in] type aType)
| queries for a new interface to an existing UNO object. More...
void | acquire ()
| increases the reference counter by one. More...
void | release ()
| decreases the reference counter by one. More...
Public Member Functions inherited from XComponent
void | dispose ()
| The owner of an object calls this method to explicitly free all resources kept by this object and thus break cyclic references. More...
void | addEventListener ([in] XEventListener xListener)
| adds an event listener to the object. More...
void | removeEventListener ([in] XEventListener aListener)
| removes an event listener from the listener list. More...

## Detailed Description

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.

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.

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.

On the other hand, in the simplest model there is only a single layer of default data which is accessible through this service.

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.

See also
  com::sun::star::configuration::ConfigurationProvider Offers the same services and creates the same accessor objects as this service, but accesses the personal configuration.

A ConfigurationProvider provides access to the personal layer of configuration data of the current user context. It should in most cases be used when using the configuration data, although for most contexts an AdministrationProvider can be used as a drop-in replacement.

## Exported Interfaces

## ◆ com::sun::star::lang::XComponent

interface com::sun::star::lang::XComponent

allows controlling or observing the lifetime of the configuration.

The owner of the provider may dispose of this object using com::sun::star::lang::XComponent::dispose().

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 snapshot views that have their own copy of the data, if available.

## ◆ com::sun::star::lang::XMultiServiceFactory

interface com::sun::star::lang::XMultiServiceFactory

allows creating access objects for specific views such as subsets and fragments of the configuration.

The parameter aServiceSpecifier passed to com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments() supports at least the service specifiers `"com.sun.star.configuration.ConfigurationAccess"` and `"com.sun.star.configuration.ConfigurationUpdateAccess"`.

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 element role as root of the view, it implements service AccessRootElement.

Using the second form requests an updatable view of the configuration. The object that is created should implement service ConfigurationUpdateAccess. To reflect its element role which includes controlling updates for the whole view, it implements service UpdateRootElement.
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.

The arguments passed to com::sun::star::lang::XMultiServiceFactory::createInstanceWithArguments() in parameter aArguments 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.

What combinations of arguments are supported depends on the service name and on the data store being administered.

With both of the standard service-specifiers above, an implementation must accept a single argument named `nodepath` 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.

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.

An implementation may ignore unknown arguments.

Some parameters that are commonly supported are described for service ConfigurationProvider.

One notable difference exists for parameter `"Locale"`. 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 `locale = "*"`.

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.

The documentation for this service was generated from the following file:

- com/sun/star/configuration/AdministrationProvider.idl