/*************************************************************************
 *
 * 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 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 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 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 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 removable.
        </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 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 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 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 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 
