/*************************************************************************
 *
 *  $RCSfile: XLayerHandler.idl,v $
 *
 *  $Revision: 1.2 $
 *
 *  last change: $Author: rt $ $Date: 2003/04/17 14:18:17 $
 *
 *  The Contents of this file are made available subject to the terms of
 *  either of the following licenses
 *
 *         - GNU Lesser General Public License Version 2.1
 *         - Sun Industry Standards Source License Version 1.1
 *
 *  Sun Microsystems Inc., October, 2000
 *
 *  GNU Lesser General Public License Version 2.1
 *  =============================================
 *  Copyright 2000 by Sun Microsystems, Inc.
 *  901 San Antonio Road, Palo Alto, CA 94303, USA
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License version 2.1, as published by the Free Software Foundation.
 *
 *  This library 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 for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 *  MA  02111-1307  USA
 *
 *
 *  Sun Industry Standards Source License Version 1.1
 *  =================================================
 *  The contents of this file are subject to the Sun Industry Standards
 *  Source License Version 1.1 (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.openoffice.org/license.html.
 *
 *  Software provided under this License is provided on an "AS IS" basis,
 *  WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
 *  WITHOUT LIMITATION, WARRANTIES THAT THE SOFTWARE IS FREE OF DEFECTS,
 *  MERCHANTABLE, FIT FOR A PARTICULAR PURPOSE, OR NON-INFRINGING.
 *  See the License for the specific provisions governing your rights and
 *  obligations concerning the Software.
 *
 *  The Initial Developer of the Original Code is: Sun Microsystems, Inc.
 *
 *  Copyright: 2002 by Sun Microsystems, Inc.
 *
 *  All Rights Reserved.
 *
 *  Contributor(s): _______________________________________
 *
 *
 ************************************************************************/
#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 #107956#
 */
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.
			</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.
			</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 
