/* -*- 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_XUpdateHandler_idl__ #define __com_sun_star_configuration_backend_XUpdateHandler_idl__ #include #include #include #include #include module com { module sun { module star { module configuration { module backend { /** receives a description of a configuration update or layer as a sequence of events. @since OOo 1.1.2 */ published interface XUpdateHandler: ::com::sun::star::uno::XInterface { /** receives notification that an update or description is started. @throws com::sun::star::configuration::backend::MalformedDataException if the update already was started @throws com::sun::star::lang::IllegalAccessException if the target layer is read-only

Some implementations can only detect this when executing XUpdateHandler::endUpdate()

@throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. */ void startUpdate( ) raises( MalformedDataException, com::sun::star::lang::IllegalAccessException, com::sun::star::lang::WrappedTargetException ); /** receives notification that the current update description is complete.

Must match a previous call to XUpdateHandler::startUpdate().

@throws com::sun::star::configuration::backend::MalformedDataException
  • if no update is started at all
  • if invalid data is detected in the update
  • if there is an unfinished subnode in progress
  • if the update tries to change read-only data

Not every implementation can detect each condition

@throws com::sun::star::lang::IllegalAccessException if the target layer is read-only @throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. */ void endUpdate( ) raises( MalformedDataException, com::sun::star::lang::IllegalAccessException, com::sun::star::lang::WrappedTargetException ); /** receives notification that a modification of a node is started.

Subsequent calls describe changes to properties and items or members of the node until a matching call to XUpdateHandler::endNode() is encountered.

@param aName specifies the name of the node. @param aAttributes specifies attribute values to be applied to the node in the current layer.

The value is a combination of NodeAttribute flags.

Only attributes which are selected in aAttributeMask are changed.

@param aAttributeMask specifies which attributes should be changed for the node.

The value is a combination of NodeAttribute flags.

@param bReset if `TRUE`, specifies that the node should be reset to its default state as given by lower layers and the schema or template prior to applying the changes. @throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't an update in progress at all
  • if a node is not valid in this place
  • if there already was a change to that node
  • if there is no node with that name
  • if the node is read-only
  • if the name is not a valid node name
  • if the attributes or mask are not valid for the node

Not every implementation can detect each condition

@throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. @see com::sun::star::configuration::backend::NodeAttribute */ void modifyNode ( [in] string aName, [in] short aAttributes, [in] short aAttributeMask, [in] boolean bReset ) raises( MalformedDataException, com::sun::star::lang::WrappedTargetException ); /** receives notification that a node is started as a new item.

The current node must be a set and a preexisting item (if any) must be removable.

The new item will be created from the default template of the set.

Subsequent calls describe the difference from the template of properties, items or members of the node until a matching call to XUpdateHandler::endNode() is encountered.

@param aName specifies the name of the new item. @param aAttributes specifies attribute values to be applied to the new node.

The value is a combination of NodeAttribute flags. Note that NodeAttribute::FUSE has an impact on the semantics of this method.

@throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a set node in progress currently
  • if there already was a change to an item of that name
  • if the template for the new node is not found
  • if an item of that name exists and is not removable
  • if the name is not a valid item name
  • if the attributes are not valid for the node

Not every implementation can detect each condition

@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 node is started as a new item based on a particular template.

The current node must be a set and a preexisting item (if any) must be removable.

Subsequent calls describe the difference from the template of properties or members of the node until a matching call to XUpdateHandler::endNode() is encountered.

@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.

The value is a combination of NodeAttribute flags. Note that NodeAttribute::FUSE has an impact on the semantics of this method.

@throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a set node in progress currently
  • if there already was a change to an item of that name
  • if the template for the new node is not found
  • if an item of that name exists and is not removable
  • if the name is not a valid item name
  • if the template is not a valid item type for the containing set
  • if the attributes are not valid for the node

Not every implementation can detect each condition

@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] short aAttributes, [in] TemplateIdentifier aTemplate ) raises( MalformedDataException, com::sun::star::lang::WrappedTargetException ); /** receives notification that a node modification is complete.

Must match the last open call to XUpdateHandler::modifyNode(), XUpdateHandler::addOrReplaceNode() or XUpdateHandler::addOrReplaceNodeFromTemplate().

@throws com::sun::star::configuration::backend::MalformedDataException
  • if invalid data is detected in the node
  • if no node is started at all

Not every implementation can detect each condition

@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 an item is to be dropped from a set.

The current node must be a set and the item must be removable.

@param aName specifies the name of the node. @throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a set node in progress currently
  • if there already was a change to a node of that name
  • if there is no item with that name
  • if the item is not removable
  • if the name is not a valid node name

Not every implementation can detect each condition

@throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. */ void removeNode( [in] string aName ) raises( MalformedDataException, com::sun::star::lang::WrappedTargetException ); /** receives notification that modification of an existing property is started.

Subsequent calls describe changes to the value(s) of the property until a matching call to XUpdateHandler::endProperty() is encountered.

@param aName specifies the name of the property. @param aAttributes specifies new attributes of the property.

The value is a combination of NodeAttribute flags.

Only attributes which are selected in aAttributeMask are changed.

NodeAttribute::MANDATORY need not be set and can't be removed, as dynamic properties always are mandatory in subsequent layers.

@param aAttributeMask specifies which attributes should be changed for the property.

The value is a combination of NodeAttribute flags.

@param aType specifies the type of the property.

A `VOID` type can be used to signify that the type is unknown and should not be recorded.

@throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a group or extensible node in progress currently
  • if there already was a change to a property of that name
  • if there is no property with that name
  • if the property is read-only
  • if the name is not a valid property name
  • if the attributes are not valid for the property

Not every implementation can detect each condition

@throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. @see com::sun::star::configuration::backend::NodeAttribute */ void modifyProperty( [in] string aName, [in] short aAttributes, [in] short aAttributeMask, [in] type aType ) raises( MalformedDataException, com::sun::star::lang::WrappedTargetException ); /** receives notification about a change to the value of the current property. @param aValue specifies the new value of the property.

The value must match the type of the existing property. If the property does not have the SchemaAttribute::REQUIRED flag set, the value can be `VOID`.

@throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a property modification in progress currently
  • if there already was a change to this value
  • if the type of the value is not an allowed type
  • if the value is not valid for the property

Not every implementation can detect each condition

@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 about a change to the value of the current property for a specific locale. @param aValue specifies the new value of the property for the given locale.

The value must match the type of the existing property. If the property does not have the SchemaAttribute::REQUIRED flag set, the value can be `VOID`.

@param aLocale specifies the locale that the new value applies to. @throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a property modification in progress currently
  • if the property is not localizable
  • if there already was a change to this value
  • if the type of the value is not an allowed type
  • if the value is not valid for the property
  • if the locale is not a valid locale name

Not every implementation can detect each condition

@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 the value of the current property should be reset to its default. @throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a property modification in progress currently
  • if there already was a change to this value

Not every implementation can detect each condition

@throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. @see com::sun::star::configuration::backend::NodeAttribute */ void resetPropertyValue( ) raises( MalformedDataException, com::sun::star::lang::WrappedTargetException ); /** receives notification that the value of the current property for a specific locale should be reset to its default. @param aLocale specifies the locale the change applies to. @throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a property modification in progress currently
  • if the property is not localizable
  • if there already was a change to this value
  • if the locale is not a valid locale name

Not every implementation can detect each condition

@throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. @see com::sun::star::configuration::backend::NodeAttribute */ void resetPropertyValueForLocale( [in] string aLocale ) raises( MalformedDataException, com::sun::star::lang::WrappedTargetException ); /** receives notification that a property modification is complete.

Must match the last open call to XUpdateHandler::modifyProperty().

@throws com::sun::star::configuration::backend::MalformedDataException
  • if invalid data is detected in the property
  • if no property is started at all

Not every implementation can detect each condition

@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 is reset to its default state. @param aName specifies the name of the property. @throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a group or extensible node in progress currently
  • if there already was a change to a property of that name
  • if there is no property with that name, or if the property has no default
  • if the property is read-only
  • if the name is not a valid property name

Not every implementation can detect each condition

@throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. @see com::sun::star::configuration::backend::NodeAttribute */ void resetProperty( [in] string aName ) raises( MalformedDataException, com::sun::star::lang::WrappedTargetException ); /** receives notification that a property having a value of `VOID` is added to the current node.

The current node must be extensible and a preexisting property (if any) must be removable in this layer.

@param aName specifies the name of the new property. @param aAttributes specifies the attributes of the new property.

The value is a combination of NodeAttribute flags and may also contain the SchemaAttribute::REQUIRED flag.

NodeAttribute::MANDATORY need not be set, as dynamic properties always are mandatory in subsequent layers.

@param aType specifies the type of the new property. @throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a group or extensible node in progress currently
  • if there already was a change to a property of that name
  • if a property of that name exists and is not removable
  • if the specified type is not allowed
  • if the name is not a valid property name
  • if the attributes are not valid for the property

Not every implementation can detect each condition

@throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. @see com::sun::star::configuration::backend::SchemaAttribute */ void addOrReplaceProperty( [in] string aName, [in] short aAttributes, [in] type aType ) raises( MalformedDataException, com::sun::star::lang::WrappedTargetException ); /** receives notification that a property having a non-`NULL` value is added to the current node.

The current node must be extensible and a preexisting property (if any) must be removable in this layer.

@param aName specifies the name of the new property. @param aAttributes specifies the attributes of the new property.

The value is a combination of NodeAttribute flags and may also contain the SchemaAttribute::REQUIRED flag.

NodeAttribute::MANDATORY need not be set, as dynamic properties always are mandatory in subsequent layers.

@param aValue specifies the value of the new property.

The value also determines the type. Therefore the value must not be `VOID`.

@throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a group or extensible node in progress currently
  • if there already was a change to a property of that name
  • if a property of that name exists and is not removable
  • if the type of the value is not an allowed type, or if the value is `VOID`
  • if the name is not a valid property name
  • if the attributes are not valid for the property

Not every implementation can detect each condition

@throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. @see com::sun::star::configuration::backend::SchemaAttribute */ void addOrReplacePropertyWithValue( [in] string aName, [in] short aAttributes, [in] any aValue ) raises( MalformedDataException, com::sun::star::lang::WrappedTargetException ); /** receives notification that a property is dropped from the current node.

The current node must be extensible and the property removable.

@param aName specifies the name of the property. @throws com::sun::star::configuration::backend::MalformedDataException
  • if there isn't a group or extensible node in progress currently
  • if there is no property with that name
  • if the property is not removable
  • if the name is not a valid node name

Not every implementation can detect each condition

@throws com::sun::star::lang::WrappedTargetException if an error occurs processing the event. */ void removeProperty( [in] string aName ) raises( MalformedDataException, com::sun::star::lang::WrappedTargetException ); }; }; }; }; }; }; #endif /* vim:set shiftwidth=4 softtabstop=4 expandtab: */