xref: /trunk/main/offapi/com/sun/star/configuration/backend/XLayerHandler.idl (revision 0d3a54ff)

/**************************************************************
 *
 * 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_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 OpenOffice 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