1/*************************************************************************
2 *
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * Copyright 2000, 2010 Oracle and/or its affiliates.
6 *
7 * OpenOffice.org - a multi-platform office productivity suite
8 *
9 * This file is part of OpenOffice.org.
10 *
11 * OpenOffice.org is free software: you can redistribute it and/or modify
12 * it under the terms of the GNU Lesser General Public License version 3
13 * only, as published by the Free Software Foundation.
14 *
15 * OpenOffice.org is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18 * GNU Lesser General Public License version 3 for more details
19 * (a copy is included in the LICENSE file that accompanied this code).
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * version 3 along with OpenOffice.org.  If not, see
23 * <http://www.openoffice.org/license.html>
24 * for a copy of the LGPLv3 License.
25 *
26 ************************************************************************/
27#ifndef __com_sun_star_configuration_backend_XUpdateHandler_idl__
28#define __com_sun_star_configuration_backend_XUpdateHandler_idl__
29
30#ifndef __com_sun_star_uno_XInterface_idl__
31#include <com/sun/star/uno/XInterface.idl>
32#endif
33
34#ifndef __com_sun_star_configuration_backend_TemplateIdentifier_idl__
35#include <com/sun/star/configuration/backend/TemplateIdentifier.idl>
36#endif
37
38#ifndef __com_sun_star_configuration_backend_MalformedDataException_idl__
39#include <com/sun/star/configuration/backend/MalformedDataException.idl>
40#endif
41
42#ifndef __com_sun_star_lang_WrappedTargetException_idl__
43#include <com/sun/star/lang/WrappedTargetException.idl>
44#endif
45
46#ifndef __com_sun_star_lang_IllegalAccessException_idl__
47#include <com/sun/star/lang/IllegalAccessException.idl>
48#endif
49
50//=============================================================================
51
52module com { module sun { module star { module configuration { module backend {
53
54//=============================================================================
55
56/** receives a description of a configuration update or layer
57	as a sequence of events.
58
59    @since OOo 1.1.2
60 */
61published interface XUpdateHandler: ::com::sun::star::uno::XInterface
62{
63	//-------------------------------------------------------------------------
64
65	/** receives notification that a update or description is started.
66
67		@throws com::sun::star::configuration::backend::MalformedDataException
68            if the update already was started
69
70		@throws com::sun::star::lang::IllegalAccessException
71            if the target layer is read-only
72            <p><em>Some implementations can only detect this when executing
73                <member>XUpdateHandler::endUpdate()</member></em>
74            </p>
75
76		@throws com::sun::star::lang::WrappedTargetException
77			if an error occurs processing the event.
78	 */
79	void startUpdate(  )
80			raises( MalformedDataException,
81                    com::sun::star::lang::IllegalAccessException,
82                    com::sun::star::lang::WrappedTargetException );
83	//-------------------------------------------------------------------------
84
85	/** receives notification that the current update description is complete.
86
87		<p> Must match a previous call to <member>XUpdateHandler::startUpdate()</member>.
88		</p>
89
90		@throws com::sun::star::configuration::backend::MalformedDataException
91            <ul>
92			<li>if no update is started at all</li>
93			<li>if invalid data is detected in the update</li>
94			<li>if there is an unfinished subnode in progress</li>
95			<li>if the update tries to change read-only data</li>
96            </ul>
97            <p><em>Not every implementation can detect each condition</em></p>
98
99		@throws com::sun::star::lang::IllegalAccessException
100            if the target layer is read-only
101
102		@throws com::sun::star::lang::WrappedTargetException
103			if an error occurs processing the event.
104	 */
105	void endUpdate(  )
106			raises( MalformedDataException,
107                    com::sun::star::lang::IllegalAccessException,
108                    com::sun::star::lang::WrappedTargetException );
109	//-------------------------------------------------------------------------
110
111	/** receives notification that a modification of a node is started.
112
113		<p> Subsequent calls describe changes to properties and items or
114			members of the node until a matching call to
115			<member>XUpdateHandler::endNode()</member> is encountered.
116		</p>
117
118		@param aName
119			specifies the name of the node.
120
121		@param aAttributes
122			specifies attribute values to be applied to the node in the
123            current layer.
124
125			<p> The value is a combination of
126				<type>NodeAttribute</type> flags.
127			</p>
128			<p>	Only attributes which are selected in aAttributeMask
129                are changed.
130			</p>
131
132		@param aAttributeMask
133			specifies which attributes should be changed for the node.
134
135			<p> The value is a combination of
136				<type>NodeAttribute</type> flags.
137			</p>
138
139		@param bReset
140			if <TRUE/>, specifies that the node should be reset to its default
141            state as given by lower layers and the schema or template prior
142            to applying the changes.
143
144		@throws com::sun::star::configuration::backend::MalformedDataException
145            <ul>
146			<li>if there isn't an update in progress at all</li>
147            <li>if a node is not valid in this place</li>
148			<li>if there already was a change to that node</li>
149			<li>if there is no node with that name</li>
150			<li>if the node is read-only</li>
151			<li>if the name is not a valid node name</li>
152			<li>if the attributes or mask are not valid for the node</li>
153            </ul>
154            <p><em>Not every implementation can detect each condition</em></p>
155
156		@throws com::sun::star::lang::WrappedTargetException
157			if an error occurs processing the event.
158
159		@see com::sun::star::configuration::backend::NodeAttribute
160	 */
161	void modifyNode ( [in] string aName,
162					  [in] short  aAttributes,
163					  [in] short  aAttributeMask,
164                      [in] boolean bReset )
165			raises( MalformedDataException,
166                    com::sun::star::lang::WrappedTargetException );
167	//-------------------------------------------------------------------------
168
169	/** receives notification that a node is started as a new item.
170
171		<p> The current node must be a set and
172			a preexisting item (if any) must be removeable.
173		</p>
174		<p> The new item will be created from the default template
175			of the set.
176		</p>
177		<p> Subsequent calls describe the difference from the template
178			of properties, items or members of the node until a matching call
179			to <member>XUpdateHandler::endNode()</member> is encountered.
180		</p>
181
182		@param aName
183			specifies the name of the new item.
184
185		@param aAttributes
186			specifies attribute values to be applied to the new node.
187
188			<p> The value is a combination of
189				<type>NodeAttribute</type> flags.  Note that
190                <member>NodeAttribute::FUSE</member> has an impact on the
191                semantics of this method.
192			</p>
193
194		@throws com::sun::star::configuration::backend::MalformedDataException
195            <ul>
196			<li>if there isn't a set node in progress currently</li>
197			<li>if there already was a change to an item of that name</li>
198			<li>if the template for the new node is not found</li>
199			<li>if an item of that name exists and is not removeable</li>
200			<li>if the name is not a valid item name</li>
201			<li>if the attributes are not valid for the node</li>
202            </ul>
203            <p><em>Not every implementation can detect each condition</em></p>
204
205		@throws com::sun::star::lang::WrappedTargetException
206			if an error occurs processing the event.
207
208		@see com::sun::star::configuration::backend::NodeAttribute
209	 */
210	void addOrReplaceNode (	[in] string aName,
211							[in] short  aAttributes )
212			raises( MalformedDataException,
213                    com::sun::star::lang::WrappedTargetException );
214	//-------------------------------------------------------------------------
215
216	/** receives notification that a node is started as a new item
217        based on a particular template.
218
219		<p> The current node must be a set and
220			a preexisting item (if any) must be removeable.
221		</p>
222		<p> Subsequent calls describe the difference from the template
223			of properties or members of the node until a matching call
224			to <member>XUpdateHandler::endNode()</member> is encountered.
225		</p>
226
227		@param aName
228			specifies the name of the item.
229
230		@param aTemplate
231			specifies the template to use for the new node
232
233		@param aAttributes
234			specifies attribute values to be applied to the new node.
235
236			<p> The value is a combination of
237				<type>NodeAttribute</type> flags.  Note that
238                <member>NodeAttribute::FUSE</member> has an impact on the
239                semantics of this method.
240			</p>
241
242		@throws com::sun::star::configuration::backend::MalformedDataException
243            <ul>
244			<li>if there isn't a set node in progress currently</li>
245			<li>if there already was a change to an item of that name</li>
246			<li>if the template for the new node is not found</li>
247			<li>if an item of that name exists and is not removeable</li>
248			<li>if the name is not a valid item name</li>
249			<li>if the template is not a valid item type for the containing set</li>
250			<li>if the attributes are not valid for the node</li>
251            </ul>
252            <p><em>Not every implementation can detect each condition</em></p>
253
254		@throws com::sun::star::lang::WrappedTargetException
255			if an error occurs processing the event.
256
257		@see com::sun::star::configuration::backend::NodeAttribute
258	 */
259	void addOrReplaceNodeFromTemplate(	[in] string aName,
260										[in] short  aAttributes,
261										[in] TemplateIdentifier aTemplate )
262			raises( MalformedDataException,
263                    com::sun::star::lang::WrappedTargetException );
264	//-------------------------------------------------------------------------
265
266	/** receives notification that a node modification is complete.
267
268		<p> Must match the last open call to
269			<member>XUpdateHandler::modifyNode()</member>,
270			<member>XUpdateHandler::addOrReplaceNode()</member> or
271			<member>XUpdateHandler::addOrReplaceNodeFromTemplate()</member>.
272		</p>
273
274		@throws com::sun::star::configuration::backend::MalformedDataException
275            <ul>
276			<li>if invalid data is detected in the node</li>
277			<li>if no node is started at all</li>
278            </ul>
279            <p><em>Not every implementation can detect each condition</em></p>
280
281		@throws com::sun::star::lang::WrappedTargetException
282			if an error occurs processing the event.
283	 */
284	void endNode( )
285			raises( MalformedDataException,
286                    com::sun::star::lang::WrappedTargetException );
287	//-------------------------------------------------------------------------
288
289	/** receives notification that an item is to be dropped from a set.
290
291		<p> The current node must be a set and
292			the item must be removeable.
293		</p>
294
295		@param aName
296			specifies the name of the node.
297
298		@throws com::sun::star::configuration::backend::MalformedDataException
299            <ul>
300			<li>if there isn't a set node in progress currently</li>
301			<li>if there already was a change to a node of that name</li>
302			<li>if there is no item with that name</li>
303			<li>if the item is not removeable</li>
304			<li>if the name is not a valid node name</li>
305            </ul>
306            <p><em>Not every implementation can detect each condition</em></p>
307
308		@throws com::sun::star::lang::WrappedTargetException
309			if an error occurs processing the event.
310	 */
311	void removeNode( [in] string aName )
312			raises( MalformedDataException,
313                    com::sun::star::lang::WrappedTargetException );
314	//-------------------------------------------------------------------------
315
316	/** receives notification that modification of an existing property is started. .
317
318		<p> Subsequent calls describe changes to the value(s)
319			of the property until a matching call to
320			<member>XUpdateHandler::endProperty()</member> is encountered.
321		</p>
322
323		@param aName
324			specifies the name of the property.
325
326		@param aAttributes
327			specifies new attributes of the property.
328
329			<p> The value is a combination of
330				<type>NodeAttribute</type> flags.
331			</p>
332			<p> Only attributes which are selected in aAttributeMask are changed.
333			</p>
334			<p>	<const>NodeAttribute::MANDATORY</const> need not be set
335                and can't be removed, as dynamic properties always are mandatory
336				in subsequent layers.
337			</p>
338
339		@param aAttributeMask
340			specifies which attributes should be changed for the property.
341
342			<p> The value is a combination of
343				<type>NodeAttribute</type> flags.
344			</p>
345
346		@param aType
347			specifies the type of the property.
348
349			<p> A <void/> type can be used to signify that
350				the type is unknown and should not be recorded.
351			</p>
352
353		@throws com::sun::star::configuration::backend::MalformedDataException
354            <ul>
355			<li>if there isn't a group or extensible node in progress currently</li>
356			<li>if there already was a change to a property of that name</li>
357			<li>if there is no property with that name</li>
358			<li>if the property is read-only</li>
359			<li>if the name is not a valid property name</li>
360			<li>if the attributes are not valid for the property</li>
361            </ul>
362            <p><em>Not every implementation can detect each condition</em></p>
363
364		@throws com::sun::star::lang::WrappedTargetException
365			if an error occurs processing the event.
366
367		@see com::sun::star::configuration::backend::NodeAttribute
368	 */
369	void modifyProperty( [in] string aName,
370			 	         [in] short aAttributes,
371			 			 [in] short aAttributeMask,
372						 [in] type aType )
373			raises( MalformedDataException,
374                    com::sun::star::lang::WrappedTargetException );
375	//-------------------------------------------------------------------------
376
377	/** receives notification about a change to the value of
378        the current property.
379
380		@param aValue
381			specifies the new value of the property.
382
383			<p> The value must match the type of the existing property.
384				If the property does not have the
385				<const>SchemaAttribute::REQUIRED</const> flag set,
386				the value can be <void/>.
387			</p>
388
389		@throws com::sun::star::configuration::backend::MalformedDataException
390            <ul>
391			<li>if there isn't a property modification in progress currently</li>
392			<li>if there already was a change to this value</li>
393			<li>if the type of the value is not an allowed type</li>
394			<li>if the value is not valid for the property</li>
395            </ul>
396            <p><em>Not every implementation can detect each condition</em></p>
397
398		@throws com::sun::star::lang::WrappedTargetException
399			if an error occurs processing the event.
400
401		@see com::sun::star::configuration::backend::NodeAttribute
402	 */
403	void setPropertyValue( [in] any aValue )
404			raises( MalformedDataException,
405                    com::sun::star::lang::WrappedTargetException );
406	//-------------------------------------------------------------------------
407
408	/** receives notification about a change to the value of
409        the current property for a specific locale.
410
411		@param aValue
412			specifies the new value of the property for the given locale.
413
414			<p> The value must match the type of the existing property.
415				If the property does not have the
416				<const>SchemaAttribute::REQUIRED</const> flag set,
417				the value can be <void/>.
418			</p>
419
420		@param aLocale
421			specifies the locale that the new value applies to.
422
423		@throws com::sun::star::configuration::backend::MalformedDataException
424            <ul>
425			<li>if there isn't a property modification in progress currently</li>
426			<li>if the property is not localizable</li>
427			<li>if there already was a change to this value</li>
428			<li>if the type of the value is not an allowed type</li>
429			<li>if the value is not valid for the property</li>
430			<li>if the locale is not a valid locale name</li>
431            </ul>
432            <p><em>Not every implementation can detect each condition</em></p>
433
434		@throws com::sun::star::lang::WrappedTargetException
435			if an error occurs processing the event.
436
437		@see com::sun::star::configuration::backend::NodeAttribute
438	 */
439	void setPropertyValueForLocale( [in] any aValue, [in] string aLocale )
440			raises( MalformedDataException,
441                    com::sun::star::lang::WrappedTargetException );
442	//-------------------------------------------------------------------------
443
444	/** receives notification that the value of the current property
445        should be reset to its default.
446
447		@throws com::sun::star::configuration::backend::MalformedDataException
448            <ul>
449			<li>if there isn't a property modification in progress currently</li>
450			<li>if there already was a change to this value</li>
451            </ul>
452            <p><em>Not every implementation can detect each condition</em></p>
453
454		@throws com::sun::star::lang::WrappedTargetException
455			if an error occurs processing the event.
456
457		@see com::sun::star::configuration::backend::NodeAttribute
458	 */
459	void resetPropertyValue( )
460			raises( MalformedDataException,
461                    com::sun::star::lang::WrappedTargetException );
462	//-------------------------------------------------------------------------
463
464	/** receives notification that the value of the current property
465        for a specific locale should be reset to its default.
466
467		@param aLocale
468			specifies the locale the change applies to.
469
470		@throws com::sun::star::configuration::backend::MalformedDataException
471            <ul>
472			<li>if there isn't a property modification in progress currently</li>
473			<li>if the property is not localizable</li>
474			<li>if there already was a change to this value</li>
475			<li>if the locale is not a valid locale name</li>
476            </ul>
477            <p><em>Not every implementation can detect each condition</em></p>
478
479		@throws com::sun::star::lang::WrappedTargetException
480			if an error occurs processing the event.
481
482		@see com::sun::star::configuration::backend::NodeAttribute
483	 */
484	void resetPropertyValueForLocale( [in] string aLocale )
485			raises( MalformedDataException,
486                    com::sun::star::lang::WrappedTargetException );
487	//-------------------------------------------------------------------------
488
489	/** receives notification that a property modification is complete.
490
491		<p> Must match the last open call to
492			<member>XUpdateHandler::modifyProperty()</member>.
493		</p>
494
495		@throws com::sun::star::configuration::backend::MalformedDataException
496            <ul>
497			<li>if invalid data is detected in the property</li>
498			<li>if no property is started at all</li>
499            </ul>
500            <p><em>Not every implementation can detect each condition</em></p>
501
502		@throws com::sun::star::lang::WrappedTargetException
503			if an error occurs processing the event.
504	 */
505	void endProperty( )
506			raises( MalformedDataException,
507                    com::sun::star::lang::WrappedTargetException );
508	//-------------------------------------------------------------------------
509
510	/** receives notification that a property is reset to its default state.
511
512		@param aName
513			specifies the name of the property.
514
515		@throws com::sun::star::configuration::backend::MalformedDataException
516            <ul>
517			<li>if there isn't a group or extensible node in progress currently</li>
518			<li>if there already was a change to a property of that name</li>
519			<li>if there is no property with that name, or if the property
520			    has no default</li>
521			<li>if the property is read-only</li>
522			<li>if the name is not a valid property name</li>
523            </ul>
524            <p><em>Not every implementation can detect each condition</em></p>
525
526		@throws com::sun::star::lang::WrappedTargetException
527			if an error occurs processing the event.
528
529		@see com::sun::star::configuration::backend::NodeAttribute
530	 */
531	void resetProperty(	[in] string aName )
532			raises( MalformedDataException,
533                    com::sun::star::lang::WrappedTargetException );
534	//-------------------------------------------------------------------------
535
536	/** receives notification that a property having a value of <void/>
537		is added to the current node.
538
539		<p> The current node must be extensible and
540			a preexisting property (if any) must be
541            removeable in this layer.
542		</p>
543
544		@param aName
545			specifies the name of the new property.
546
547		@param aAttributes
548			specifies the attributes of the new property.
549
550			<p> The value is a combination of
551				<type>NodeAttribute</type> flags and may also contain the
552				<const>SchemaAttribute::REQUIRED</const> flag.
553			</p>
554			</p>
555			<p>	<const>NodeAttribute::MANDATORY</const> need not be set,
556				as dynamic properties always are mandatory
557				in subsequent layers.
558			</p>
559
560		@param aType
561			specifies the type of the new property.
562
563		@throws com::sun::star::configuration::backend::MalformedDataException
564            <ul>
565			<li>if there isn't a group or extensible node in progress currently</li>
566			<li>if there already was a change to a property of that name</li>
567			<li>if a property of that name exists and is not removeable</li>
568			<li>if the specified type is not allowed</li>
569			<li>if the name is not a valid property name</li>
570			<li>if the attributes are not valid for the property</li>
571            </ul>
572            <p><em>Not every implementation can detect each condition</em></p>
573
574		@throws com::sun::star::lang::WrappedTargetException
575			if an error occurs processing the event.
576
577		@see com::sun::star::configuration::backend::SchemaAttribute
578	 */
579	void addOrReplaceProperty( [in] string aName,
580			 				   [in] short aAttributes,
581							   [in] type aType )
582			raises( MalformedDataException,
583                    com::sun::star::lang::WrappedTargetException );
584	//-------------------------------------------------------------------------
585
586	/** receives notification that a property having a non-<NULL/> value
587		is added to the current node.
588
589		<p> The current node must be extensible and
590			a preexisting property (if any) must be
591            removeable in this layer.
592		</p>
593
594		@param aName
595			specifies the name of the new property.
596
597		@param aAttributes
598			specifies the attributes of the new property.
599
600			<p> The value is a combination of
601				<type>NodeAttribute</type> flags and may also contain the
602				<const>SchemaAttribute::REQUIRED</const> flag.
603			</p>
604			</p>
605			<p>	<const>NodeAttribute::MANDATORY</const> need not be set,
606				as dynamic properties always are mandatory
607				in subsequent layers.
608			</p>
609
610		@param aValue
611			specifies the value of the new property.
612
613			<p> The value also determines the type.
614				Therefore the value must not be <void/>.
615			</p>
616
617		@throws com::sun::star::configuration::backend::MalformedDataException
618            <ul>
619			<li>if there isn't a group or extensible node in progress currently</li>
620			<li>if there already was a change to a property of that name</li>
621			<li>if a property of that name exists and is not removeable</li>
622			<li>if the type of the value is not an allowed type,
623			    or if the value is <void/></li>
624			<li>if the name is not a valid property name</li>
625			<li>if the attributes are not valid for the property</li>
626            </ul>
627            <p><em>Not every implementation can detect each condition</em></p>
628
629		@throws com::sun::star::lang::WrappedTargetException
630			if an error occurs processing the event.
631
632		@see com::sun::star::configuration::backend::SchemaAttribute
633	 */
634	void addOrReplacePropertyWithValue(	[in] string aName,
635			 							[in] short aAttributes,
636										[in] any aValue )
637			raises( MalformedDataException,
638                    com::sun::star::lang::WrappedTargetException );
639	//-------------------------------------------------------------------------
640
641	/** receives notification that a property is dropped from the current node.
642
643		<p>The current node must be extensible and the property removeable.</p>
644
645		@param aName
646			specifies the name of the property.
647
648		@throws com::sun::star::configuration::backend::MalformedDataException
649            <ul>
650			<li>if there isn't a group or extensible node in progress currently</li>
651			<li>if there is no property with that name</li>
652			<li>if the property is not removeable</li>
653			<li>if the name is not a valid node name</li>
654            </ul>
655            <p><em>Not every implementation can detect each condition</em></p>
656
657		@throws com::sun::star::lang::WrappedTargetException
658			if an error occurs processing the event.
659	 */
660	void removeProperty( [in] string aName )
661			raises( MalformedDataException,
662                    com::sun::star::lang::WrappedTargetException );
663	//-------------------------------------------------------------------------
664
665};
666
667//=============================================================================
668
669}; }; }; }; };
670
671//=============================================================================
672
673#endif
674