path: root/offapi/com/sun/star/configuration/backend/XLayerHandler.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/*
 * This file is part of the LibreOffice project.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * This file incorporates work covered by the following license notice:
 *
 *   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 .
 */
#ifndef __com_sun_star_configuration_backend_XLayerHandler_idl__
#define __com_sun_star_configuration_backend_XLayerHandler_idl__

#include <com/sun/star/uno/XInterface.idl>
#include <com/sun/star/configuration/backend/TemplateIdentifier.idl>

#include <com/sun/star/configuration/backend/MalformedDataException.idl>
#include <com/sun/star/lang/WrappedTargetException.idl>


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 XLayerHandler::endLayer()
            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 XLayerHandler::startLayer().
        </p>

        @throws com::sun::star::configuration::backend::MalformedDataException
            <ul>
            <li>if invalid data is detected in the layer</li>
            <li>if there is an 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
            XLayerHandler::endNode()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
                NodeAttribute 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 XLayerHandler::endNode()
            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
                NodeAttribute flags.  Note that
                NodeAttribute::FUSE 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 XLayerHandler::endNode()
            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
                NodeAttribute flags.  Note that
                NodeAttribute::FUSE 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
            XLayerHandler::overrideNode(),
            XLayerHandler::addOrReplaceNode() or
            XLayerHandler::addOrReplaceNodeFromTemplate().
        </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 XLayerHandler::endProperty()
            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
                NodeAttribute 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
                com::sun::star::uno::TypeClass::ANY.)
            </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. `string` or - for list values -
                `string[]`.) 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
                SchemaAttribute::REQUIRED 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
                SchemaAttribute::REQUIRED 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
            XLayerHandler::overrideProperty(),
        </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
                NodeAttribute flags and may also contain the
                SchemaAttribute::REQUIRED flag.
            </p>
            <p> NodeAttribute::MANDATORY 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
                NodeAttribute flags and may also contain the
                SchemaAttribute::REQUIRED flag.
            </p>
            </p>
            <p> NodeAttribute::MANDATORY 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

/* vim:set shiftwidth=4 softtabstop=4 expandtab: */