Google Git
Sign in
apache / openoffice / bab44dcac0296df22024f3f10e7997de78ed4094 / . / AOO410 / main / offapi / com / sun / star / configuration / backend / XUpdateHandler.idl
blob: 66e9fe1d905e5daa8254a4c8bbb1346577ef5e24 [file] [log] [blame]
/**************************************************************
*
* 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
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*
*************************************************************/
#ifndef __com_sun_star_configuration_backend_XUpdateHandler_idl__
#define __com_sun_star_configuration_backend_XUpdateHandler_idl__
#ifndef __com_sun_star_uno_XInterface_idl__
#include <com/sun/star/uno/XInterface.idl>
#endif
#ifndef __com_sun_star_configuration_backend_TemplateIdentifier_idl__
#include <com/sun/star/configuration/backend/TemplateIdentifier.idl>
#endif
#ifndef __com_sun_star_configuration_backend_MalformedDataException_idl__
#include <com/sun/star/configuration/backend/MalformedDataException.idl>
#endif
#ifndef __com_sun_star_lang_WrappedTargetException_idl__
#include <com/sun/star/lang/WrappedTargetException.idl>
#endif
#ifndef __com_sun_star_lang_IllegalAccessException_idl__
#include <com/sun/star/lang/IllegalAccessException.idl>
#endif
//=============================================================================
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 OpenOffice 1.1.2
*/
published interface XUpdateHandler: ::com::sun::star::uno::XInterface
{
//-------------------------------------------------------------------------
/** receives notification that a 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
<member>XUpdateHandler::endUpdate()</member></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 <member>XUpdateHandler::startUpdate()</member>.
</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
<member>XUpdateHandler::endNode()</member> 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
<type>NodeAttribute</type> 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
<type>NodeAttribute</type> 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 removeable.
</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 <member>XUpdateHandler::endNode()</member> 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
<type>NodeAttribute</type> flags. Note that
<member>NodeAttribute::FUSE</member> 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 removeable</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 removeable.
</p>
<p> Subsequent calls describe the difference from the template
of properties or members of the node until a matching call
to <member>XUpdateHandler::endNode()</member> 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
<type>NodeAttribute</type> flags. Note that
<member>NodeAttribute::FUSE</member> 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 removeable</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
<member>XUpdateHandler::modifyNode()</member>,
<member>XUpdateHandler::addOrReplaceNode()</member> or
<member>XUpdateHandler::addOrReplaceNodeFromTemplate()</member>.
</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 removeable.
</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 removeable</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
<member>XUpdateHandler::endProperty()</member> 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
<type>NodeAttribute</type> flags.
</p>
<p> Only attributes which are selected in aAttributeMask are changed.
</p>
<p> <const>NodeAttribute::MANDATORY</const> 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
<type>NodeAttribute</type> 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
<const>SchemaAttribute::REQUIRED</const> 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
<const>SchemaAttribute::REQUIRED</const> 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
<member>XUpdateHandler::modifyProperty()</member>.
</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
removeable 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
<type>NodeAttribute</type> flags and may also contain the
<const>SchemaAttribute::REQUIRED</const> flag.
</p>
</p>
<p> <const>NodeAttribute::MANDATORY</const> 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 removeable</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
removeable 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
<type>NodeAttribute</type> flags and may also contain the
<const>SchemaAttribute::REQUIRED</const> flag.
</p>
</p>
<p> <const>NodeAttribute::MANDATORY</const> 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 removeable</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 removeable.</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 removeable</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 );
//-------------------------------------------------------------------------
};
//=============================================================================
}; }; }; }; };
//=============================================================================
#endif