diff options
Diffstat (limited to 'offapi/com/sun/star/configuration/backend/XLayerHandler.idl')
| -rw-r--r-- | offapi/com/sun/star/configuration/backend/XLayerHandler.idl | 570 |
1 files changed, 570 insertions, 0 deletions
diff --git a/offapi/com/sun/star/configuration/backend/XLayerHandler.idl b/offapi/com/sun/star/configuration/backend/XLayerHandler.idl new file mode 100644 index 000000000000..22b75c9466dc --- /dev/null +++ b/offapi/com/sun/star/configuration/backend/XLayerHandler.idl @@ -0,0 +1,570 @@ +/************************************************************************* + * + * 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_XLayerHandler_idl__ +#define __com_sun_star_configuration_backend_XLayerHandler_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 + +//============================================================================= + +module com { module sun { module star { module configuration { module backend { + +//============================================================================= + +/** receives a description of a configuration layer + as a sequence of events. + + @since OOo 1.1.2 + */ +published interface XLayerHandler: ::com::sun::star::uno::XInterface +{ + //------------------------------------------------------------------------- + + /** receives notification that a layer description is started + for a component. + + <p> Subsequent calls describe the contents of the layer + until a matching call to <member>XLayerHandler::endLayer()</member> + is encountered. + </p> + + @throws com::sun::star::configuration::backend::MalformedDataException + if there is an unfinished layer in progress + + @throws com::sun::star::lang::WrappedTargetException + if an error occurs processing the event. + */ + void startLayer( ) + raises( MalformedDataException, + com::sun::star::lang::WrappedTargetException ); + //------------------------------------------------------------------------- + + /** receives notification that a layer description is complete. + + <p> Must match a previous call to <member>XLayerHandler::startLayer()</member>. + </p> + + @throws com::sun::star::configuration::backend::MalformedDataException + <ul> + <li>if invalid data is detected in the layer</li> + <li>if there is a unfinished subnode in progress</li> + <li>if no layer is started at all</li> + <li>if the layer tries to override read-only or final data</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 endLayer( ) + raises( MalformedDataException, + com::sun::star::lang::WrappedTargetException ); + //------------------------------------------------------------------------- + + /** receives notification that a description of a node override is started. + + <p> Subsequent calls describe overrides to properties and members + or items of the node until a matching call to + <member>XLayerHandler::endNode()</member>is encountered. + </p> + + @param aName + specifies the name of the node. + + @param aAttributes + specifies attribute values to be applied to the node. + + <p> The value is a combination of + <type>NodeAttribute</type> flags. + </p> + <p> The attributes are combined cumulatively with those + set on lower layers. + </p> + + @param bClear + if <TRUE/>, specifies that the node should be cleared to an empty + state by removing all non-mandatory children from lower layers prior + to applying the overrides. + + @throws com::sun::star::configuration::backend::MalformedDataException + <ul> + <li>if there isn't a layer in progress</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 marked read-only in a lower layer</li> + <li>if the name is not a valid node 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 overrideNode( [in] string aName, + [in] short aAttributes, + [in] boolean bClear ) + raises( MalformedDataException, + com::sun::star::lang::WrappedTargetException ); + //------------------------------------------------------------------------- + + /** receives notification that a new item is started. + + <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 and members or items of the node until + a matching call to <member>XLayerHandler::endNode()</member> + is encountered. + </p> + + @param aName + specifies the name of the 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 a node of that name</li> + <li>if the template for the new node is not found</li> + <li>if an item of that name on a lower layer 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 new item based on a particular template + is started. + + <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 and members or items of the node until + a matching call to <member>XLayerHandler::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 a node of that name</li> + <li>if the template for the new node is not found</li> + <li>if the template is not a valid item type for the containing set</li> + <li>if an item of that name on a lower layer 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 addOrReplaceNodeFromTemplate( [in] string aName, + [in] TemplateIdentifier aTemplate, + [in] short aAttributes ) + raises( MalformedDataException, + com::sun::star::lang::WrappedTargetException ); + //------------------------------------------------------------------------- + + /** receives notification that a node description is complete. + + <p> Must match the last open call to + <member>XLayerHandler::overrideNode()</member>, + <member>XLayerHandler::addOrReplaceNode()</member> or + <member>XLayerHandler::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 a node is 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 dropNode( [in] string aName ) + raises( MalformedDataException, + com::sun::star::lang::WrappedTargetException ); + //------------------------------------------------------------------------- + + /** receives notification that an existing property is modified. + + <p> Subsequent calls describe new value(s) for the property until a + matching call to <member>XLayerHandler::endProperty()</member> + is encountered. + </p> + + @param aName + specifies the name of the property. + + @param aAttributes + specifies the new attributes of the property. + + <p> The value is a combination of + <type>NodeAttribute</type> flags. + </p> + <p> The attributes are combined cumulatively with those + set on lower layers. + </p> + + @param aType + specifies the type of the property. + + <p> This must be the same type as is already defined in the schema + or lower layers, unless the previous type was unspecified + (as indicated by + <const scope="com::sun::star::uno">TypeClass::ANY</const>.) + </p> + <p> A <void/> type indicates that the type is unspecified + in this layer. + In this case any subsequent value may be of a generic type + (e.g. <atom>string</atom> or - for list values - + <atom dim="[]">string</atom>.) Such values may be + converted to the type defined in the schema by + the implementation. + </p> + + @param bClear + if <TRUE/>, specifies that the property should be cleared to an empty + state by discarding all values from lower layers prior + to applying the overrides. + + @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 type does not match the type of the property</li> + <li>if a type is missing and cannot be determined otherwise</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 overrideProperty( [in] string aName, + [in] short aAttributes, + [in] type aType, + [in] boolean bClear ) + raises( MalformedDataException, + com::sun::star::lang::WrappedTargetException ); + + //------------------------------------------------------------------------- + + /** receives notification that the value of the current property + is overridden. . + + @param aValue + specifies the new value of the property. + + <p> The value must match the type of the current property. + If the property does not have the + <const>SchemaAttribute::REQUIRED</const> flag set, + the value can be <void/>. + </p> + <p> If the current property is localized, this value applies + to the default locale. + </p> + + @throws com::sun::star::configuration::backend::MalformedDataException + <ul> + <li>if there isn't a property in progress currently</li> + <li>if there already was a change to the value of that property</li> + <li>if the value does not have the proper 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 that the value of the current localized property + is overridden for a specific locale . + + @param aValue + specifies the new value of the property. + + <p> The value must match the type of the current 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 this value should apply to. + + @throws com::sun::star::configuration::backend::MalformedDataException + <ul> + <li>if there isn't a property in progress currently</li> + <li>if the current property isn't localized</li> + <li>if there already was a change to the property for that locale</li> + <li>if the value does not have the proper type</li> + <li>if the value is not valid for the property</li> + <li>if the locale is not a valid locale</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 a property description is complete. + + <p> Must match an open call to + <member>XLayerHandler::overrideProperty()</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 having a <void/> value is added + to the current node. + + <p> The current node must be extensible. + </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> <const>NodeAttribute::MANDATORY</const> need not be set, + as dynamically added 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 an extensible node in progress currently</li> + <li>if a property with that name already exists</li> + <li>if the specified type is not allowed for a property</li> + <li>if the name is not a valid property name</li> + <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 addProperty( [in] string aName, + [in] short aAttributes, + [in] type aType ) + raises( MalformedDataException, + com::sun::star::lang::WrappedTargetException ); + + //------------------------------------------------------------------------- + + /** receives notification that a property having a non-<void/> value + is added to the current node. + + <p> The current node must be extensible. + </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 an extensible node in progress currently</li> + <li>if a property with that name already exists</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 value is not valid for the property</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 addPropertyWithValue( [in] string aName, + [in] short aAttributes, + [in] any aValue ) + raises( MalformedDataException, + com::sun::star::lang::WrappedTargetException ); + + //------------------------------------------------------------------------- +}; + +//============================================================================= + +}; }; }; }; }; + +//============================================================================= + +#endif |