622 lines
24 KiB
Text
622 lines
24 KiB
Text
/* -*- 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 .
|
|
*/
|
|
|
|
|
|
module com { module sun { module star { module configuration { module backend {
|
|
|
|
|
|
/** receives a description of a configuration update or layer
|
|
as a sequence of events.
|
|
|
|
@since OOo 1.1.2
|
|
*/
|
|
published interface XUpdateHandler: ::com::sun::star::uno::XInterface
|
|
{
|
|
|
|
/** receives notification that an update or description is started.
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
if the update already was started
|
|
|
|
@throws com::sun::star::lang::IllegalAccessException
|
|
if the target layer is read-only
|
|
<p><em>Some implementations can only detect this when executing
|
|
XUpdateHandler::endUpdate()</em>
|
|
</p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
*/
|
|
void startUpdate( )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::IllegalAccessException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that the current update description is complete.
|
|
|
|
<p> Must match a previous call to XUpdateHandler::startUpdate().
|
|
</p>
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if no update is started at all</li>
|
|
<li>if invalid data is detected in the update</li>
|
|
<li>if there is an unfinished subnode in progress</li>
|
|
<li>if the update tries to change read-only data</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::IllegalAccessException
|
|
if the target layer is read-only
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
*/
|
|
void endUpdate( )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::IllegalAccessException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that a modification of a node is started.
|
|
|
|
<p> Subsequent calls describe changes to properties and items or
|
|
members of the node until a matching call to
|
|
XUpdateHandler::endNode() is encountered.
|
|
</p>
|
|
|
|
@param aName
|
|
specifies the name of the node.
|
|
|
|
@param aAttributes
|
|
specifies attribute values to be applied to the node in the
|
|
current layer.
|
|
|
|
<p> The value is a combination of
|
|
NodeAttribute flags.
|
|
</p>
|
|
<p> Only attributes which are selected in aAttributeMask
|
|
are changed.
|
|
</p>
|
|
|
|
@param aAttributeMask
|
|
specifies which attributes should be changed for the node.
|
|
|
|
<p> The value is a combination of
|
|
NodeAttribute flags.
|
|
</p>
|
|
|
|
@param bReset
|
|
if `TRUE`, specifies that the node should be reset to its default
|
|
state as given by lower layers and the schema or template prior
|
|
to applying the changes.
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't an update in progress at all</li>
|
|
<li>if a node is not valid in this place</li>
|
|
<li>if there already was a change to that node</li>
|
|
<li>if there is no node with that name</li>
|
|
<li>if the node is read-only</li>
|
|
<li>if the name is not a valid node name</li>
|
|
<li>if the attributes or mask are not valid for the node</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::NodeAttribute
|
|
*/
|
|
void modifyNode ( [in] string aName,
|
|
[in] short aAttributes,
|
|
[in] short aAttributeMask,
|
|
[in] boolean bReset )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that a node is started as a new item.
|
|
|
|
<p> The current node must be a set and
|
|
a preexisting item (if any) must be removable.
|
|
</p>
|
|
<p> The new item will be created from the default template
|
|
of the set.
|
|
</p>
|
|
<p> Subsequent calls describe the difference from the template
|
|
of properties, items or members of the node until a matching call
|
|
to XUpdateHandler::endNode() is encountered.
|
|
</p>
|
|
|
|
@param aName
|
|
specifies the name of the new item.
|
|
|
|
@param aAttributes
|
|
specifies attribute values to be applied to the new node.
|
|
|
|
<p> The value is a combination of
|
|
NodeAttribute flags. Note that
|
|
NodeAttribute::FUSE has an impact on the
|
|
semantics of this method.
|
|
</p>
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a set node in progress currently</li>
|
|
<li>if there already was a change to an item of that name</li>
|
|
<li>if the template for the new node is not found</li>
|
|
<li>if an item of that name exists and is not removable</li>
|
|
<li>if the name is not a valid item name</li>
|
|
<li>if the attributes are not valid for the node</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::NodeAttribute
|
|
*/
|
|
void addOrReplaceNode ( [in] string aName,
|
|
[in] short aAttributes )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that a node is started as a new item
|
|
based on a particular template.
|
|
|
|
<p> The current node must be a set and
|
|
a preexisting item (if any) must be removable.
|
|
</p>
|
|
<p> Subsequent calls describe the difference from the template
|
|
of properties or members of the node until a matching call
|
|
to XUpdateHandler::endNode() is encountered.
|
|
</p>
|
|
|
|
@param aName
|
|
specifies the name of the item.
|
|
|
|
@param aTemplate
|
|
specifies the template to use for the new node
|
|
|
|
@param aAttributes
|
|
specifies attribute values to be applied to the new node.
|
|
|
|
<p> The value is a combination of
|
|
NodeAttribute flags. Note that
|
|
NodeAttribute::FUSE has an impact on the
|
|
semantics of this method.
|
|
</p>
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a set node in progress currently</li>
|
|
<li>if there already was a change to an item of that name</li>
|
|
<li>if the template for the new node is not found</li>
|
|
<li>if an item of that name exists and is not removable</li>
|
|
<li>if the name is not a valid item name</li>
|
|
<li>if the template is not a valid item type for the containing set</li>
|
|
<li>if the attributes are not valid for the node</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::NodeAttribute
|
|
*/
|
|
void addOrReplaceNodeFromTemplate( [in] string aName,
|
|
[in] short aAttributes,
|
|
[in] TemplateIdentifier aTemplate )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that a node modification is complete.
|
|
|
|
<p> Must match the last open call to
|
|
XUpdateHandler::modifyNode(),
|
|
XUpdateHandler::addOrReplaceNode() or
|
|
XUpdateHandler::addOrReplaceNodeFromTemplate().
|
|
</p>
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if invalid data is detected in the node</li>
|
|
<li>if no node is started at all</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
*/
|
|
void endNode( )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that an item is to be dropped from a set.
|
|
|
|
<p> The current node must be a set and
|
|
the item must be removable.
|
|
</p>
|
|
|
|
@param aName
|
|
specifies the name of the node.
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a set node in progress currently</li>
|
|
<li>if there already was a change to a node of that name</li>
|
|
<li>if there is no item with that name</li>
|
|
<li>if the item is not removable</li>
|
|
<li>if the name is not a valid node name</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
*/
|
|
void removeNode( [in] string aName )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that modification of an existing property is
|
|
started.
|
|
|
|
<p> Subsequent calls describe changes to the value(s)
|
|
of the property until a matching call to
|
|
XUpdateHandler::endProperty() is encountered.
|
|
</p>
|
|
|
|
@param aName
|
|
specifies the name of the property.
|
|
|
|
@param aAttributes
|
|
specifies new attributes of the property.
|
|
|
|
<p> The value is a combination of
|
|
NodeAttribute flags.
|
|
</p>
|
|
<p> Only attributes which are selected in aAttributeMask are changed.
|
|
</p>
|
|
<p> NodeAttribute::MANDATORY need not be set
|
|
and can't be removed, as dynamic properties always are mandatory
|
|
in subsequent layers.
|
|
</p>
|
|
|
|
@param aAttributeMask
|
|
specifies which attributes should be changed for the property.
|
|
|
|
<p> The value is a combination of
|
|
NodeAttribute flags.
|
|
</p>
|
|
|
|
@param aType
|
|
specifies the type of the property.
|
|
|
|
<p> A `VOID` type can be used to signify that
|
|
the type is unknown and should not be recorded.
|
|
</p>
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a group or extensible node in progress currently</li>
|
|
<li>if there already was a change to a property of that name</li>
|
|
<li>if there is no property with that name</li>
|
|
<li>if the property is read-only</li>
|
|
<li>if the name is not a valid property name</li>
|
|
<li>if the attributes are not valid for the property</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::NodeAttribute
|
|
*/
|
|
void modifyProperty( [in] string aName,
|
|
[in] short aAttributes,
|
|
[in] short aAttributeMask,
|
|
[in] type aType )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification about a change to the value of
|
|
the current property.
|
|
|
|
@param aValue
|
|
specifies the new value of the property.
|
|
|
|
<p> The value must match the type of the existing property.
|
|
If the property does not have the
|
|
SchemaAttribute::REQUIRED flag set,
|
|
the value can be `VOID`.
|
|
</p>
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a property modification in progress currently</li>
|
|
<li>if there already was a change to this value</li>
|
|
<li>if the type of the value is not an allowed type</li>
|
|
<li>if the value is not valid for the property</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::NodeAttribute
|
|
*/
|
|
void setPropertyValue( [in] any aValue )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification about a change to the value of
|
|
the current property for a specific locale.
|
|
|
|
@param aValue
|
|
specifies the new value of the property for the given locale.
|
|
|
|
<p> The value must match the type of the existing property.
|
|
If the property does not have the
|
|
SchemaAttribute::REQUIRED flag set,
|
|
the value can be `VOID`.
|
|
</p>
|
|
|
|
@param aLocale
|
|
specifies the locale that the new value applies to.
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a property modification in progress currently</li>
|
|
<li>if the property is not localizable</li>
|
|
<li>if there already was a change to this value</li>
|
|
<li>if the type of the value is not an allowed type</li>
|
|
<li>if the value is not valid for the property</li>
|
|
<li>if the locale is not a valid locale name</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::NodeAttribute
|
|
*/
|
|
void setPropertyValueForLocale( [in] any aValue, [in] string aLocale )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that the value of the current property
|
|
should be reset to its default.
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a property modification in progress currently</li>
|
|
<li>if there already was a change to this value</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::NodeAttribute
|
|
*/
|
|
void resetPropertyValue( )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that the value of the current property
|
|
for a specific locale should be reset to its default.
|
|
|
|
@param aLocale
|
|
specifies the locale the change applies to.
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a property modification in progress currently</li>
|
|
<li>if the property is not localizable</li>
|
|
<li>if there already was a change to this value</li>
|
|
<li>if the locale is not a valid locale name</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::NodeAttribute
|
|
*/
|
|
void resetPropertyValueForLocale( [in] string aLocale )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that a property modification is complete.
|
|
|
|
<p> Must match the last open call to
|
|
XUpdateHandler::modifyProperty().
|
|
</p>
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if invalid data is detected in the property</li>
|
|
<li>if no property is started at all</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
*/
|
|
void endProperty( )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that a property is reset to its default state.
|
|
|
|
@param aName
|
|
specifies the name of the property.
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a group or extensible node in progress currently</li>
|
|
<li>if there already was a change to a property of that name</li>
|
|
<li>if there is no property with that name, or if the property
|
|
has no default</li>
|
|
<li>if the property is read-only</li>
|
|
<li>if the name is not a valid property name</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::NodeAttribute
|
|
*/
|
|
void resetProperty( [in] string aName )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that a property having a value of `VOID`
|
|
is added to the current node.
|
|
|
|
<p> The current node must be extensible and
|
|
a preexisting property (if any) must be
|
|
removable in this layer.
|
|
</p>
|
|
|
|
@param aName
|
|
specifies the name of the new property.
|
|
|
|
@param aAttributes
|
|
specifies the attributes of the new property.
|
|
|
|
<p> The value is a combination of
|
|
NodeAttribute flags and may also contain the
|
|
SchemaAttribute::REQUIRED flag.
|
|
</p>
|
|
</p>
|
|
<p> NodeAttribute::MANDATORY need not be set,
|
|
as dynamic properties always are mandatory
|
|
in subsequent layers.
|
|
</p>
|
|
|
|
@param aType
|
|
specifies the type of the new property.
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a group or extensible node in progress currently</li>
|
|
<li>if there already was a change to a property of that name</li>
|
|
<li>if a property of that name exists and is not removable</li>
|
|
<li>if the specified type is not allowed</li>
|
|
<li>if the name is not a valid property name</li>
|
|
<li>if the attributes are not valid for the property</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::SchemaAttribute
|
|
*/
|
|
void addOrReplaceProperty( [in] string aName,
|
|
[in] short aAttributes,
|
|
[in] type aType )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that a property having a non-`NULL` value
|
|
is added to the current node.
|
|
|
|
<p> The current node must be extensible and
|
|
a preexisting property (if any) must be
|
|
removable in this layer.
|
|
</p>
|
|
|
|
@param aName
|
|
specifies the name of the new property.
|
|
|
|
@param aAttributes
|
|
specifies the attributes of the new property.
|
|
|
|
<p> The value is a combination of
|
|
NodeAttribute flags and may also contain the
|
|
SchemaAttribute::REQUIRED flag.
|
|
</p>
|
|
</p>
|
|
<p> NodeAttribute::MANDATORY need not be set,
|
|
as dynamic properties always are mandatory
|
|
in subsequent layers.
|
|
</p>
|
|
|
|
@param aValue
|
|
specifies the value of the new property.
|
|
|
|
<p> The value also determines the type.
|
|
Therefore the value must not be `VOID`.
|
|
</p>
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a group or extensible node in progress currently</li>
|
|
<li>if there already was a change to a property of that name</li>
|
|
<li>if a property of that name exists and is not removable</li>
|
|
<li>if the type of the value is not an allowed type,
|
|
or if the value is `VOID`</li>
|
|
<li>if the name is not a valid property name</li>
|
|
<li>if the attributes are not valid for the property</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
|
|
@see com::sun::star::configuration::backend::SchemaAttribute
|
|
*/
|
|
void addOrReplacePropertyWithValue( [in] string aName,
|
|
[in] short aAttributes,
|
|
[in] any aValue )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
/** receives notification that a property is dropped from the current node.
|
|
|
|
<p>The current node must be extensible and the property removable.</p>
|
|
|
|
@param aName
|
|
specifies the name of the property.
|
|
|
|
@throws com::sun::star::configuration::backend::MalformedDataException
|
|
<ul>
|
|
<li>if there isn't a group or extensible node in progress currently</li>
|
|
<li>if there is no property with that name</li>
|
|
<li>if the property is not removable</li>
|
|
<li>if the name is not a valid node name</li>
|
|
</ul>
|
|
<p><em>Not every implementation can detect each condition</em></p>
|
|
|
|
@throws com::sun::star::lang::WrappedTargetException
|
|
if an error occurs processing the event.
|
|
*/
|
|
void removeProperty( [in] string aName )
|
|
raises( MalformedDataException,
|
|
com::sun::star::lang::WrappedTargetException );
|
|
|
|
};
|
|
|
|
|
|
}; }; }; }; };
|
|
|
|
|
|
/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
|