diff options
Diffstat (limited to 'offapi/com/sun/star/configuration/backend/XUpdateHandler.idl')
-rw-r--r-- | offapi/com/sun/star/configuration/backend/XUpdateHandler.idl | 673 |
1 files changed, 673 insertions, 0 deletions
diff --git a/offapi/com/sun/star/configuration/backend/XUpdateHandler.idl b/offapi/com/sun/star/configuration/backend/XUpdateHandler.idl new file mode 100644 index 000000000000..5545fc3bfa21 --- /dev/null +++ b/offapi/com/sun/star/configuration/backend/XUpdateHandler.idl @@ -0,0 +1,673 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 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 OOo 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 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 <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 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 <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 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 + <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 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 + <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 + 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 + <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 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 + <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 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 ); + //------------------------------------------------------------------------- + +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif |