1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_configuration_backend_XLayerHandler_idl__
24#define __com_sun_star_configuration_backend_XLayerHandler_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29
30#ifndef __com_sun_star_configuration_backend_TemplateIdentifier_idl__
31#include <com/sun/star/configuration/backend/TemplateIdentifier.idl>
32#endif
33
34#ifndef __com_sun_star_configuration_backend_MalformedDataException_idl__
35#include <com/sun/star/configuration/backend/MalformedDataException.idl>
36#endif
37
38#ifndef __com_sun_star_lang_WrappedTargetException_idl__
39#include <com/sun/star/lang/WrappedTargetException.idl>
40#endif
41
42//=============================================================================
43
44module com { module sun { module star { module configuration { module backend {
45
46//=============================================================================
47
48/** receives a description of a configuration layer
49	as a sequence of events.
50
51    @since OOo 1.1.2
52 */
53published interface XLayerHandler: ::com::sun::star::uno::XInterface
54{
55	//-------------------------------------------------------------------------
56
57	/** receives notification that a layer description is started
58		for a component.
59
60		<p> Subsequent calls describe the contents of the layer
61			until a matching call to <member>XLayerHandler::endLayer()</member>
62			is encountered.
63		</p>
64
65		@throws com::sun::star::configuration::backend::MalformedDataException
66			if there is an unfinished layer in progress
67
68		@throws com::sun::star::lang::WrappedTargetException
69			if an error occurs processing the event.
70	 */
71	void startLayer(  )
72			raises( MalformedDataException,
73                    com::sun::star::lang::WrappedTargetException );
74	//-------------------------------------------------------------------------
75
76	/** receives notification that a layer description is complete.
77
78		<p> Must match a previous call to <member>XLayerHandler::startLayer()</member>.
79		</p>
80
81		@throws com::sun::star::configuration::backend::MalformedDataException
82            <ul>
83			<li>if invalid data is detected in the layer</li>
84			<li>if there is a unfinished subnode in progress</li>
85			<li>if no layer is started at all</li>
86			<li>if the layer tries to override read-only or final data</li>
87            </ul>
88            <p><em>Not every implementation can detect each condition</em></p>
89
90		@throws com::sun::star::lang::WrappedTargetException
91			if an error occurs processing the event.
92	 */
93	void endLayer(  )
94			raises( MalformedDataException,
95                    com::sun::star::lang::WrappedTargetException );
96	//-------------------------------------------------------------------------
97
98	/** receives notification that a description of a node override is started.
99
100		<p> Subsequent calls describe overrides to properties and members
101			or items of the node until a matching call to
102			<member>XLayerHandler::endNode()</member>is encountered.
103		</p>
104
105		@param aName
106			specifies the name of the node.
107
108		@param aAttributes
109			specifies attribute values to be applied to the node.
110
111			<p> The value is a combination of
112				<type>NodeAttribute</type> flags.
113			</p>
114			<p>	The attributes are combined cumulatively with those
115                set on lower layers.
116			</p>
117
118		@param bClear
119			if <TRUE/>, specifies that the node should be cleared to an empty
120            state by removing all non-mandatory children from lower layers prior
121            to applying the overrides.
122
123		@throws com::sun::star::configuration::backend::MalformedDataException
124            <ul>
125			<li>if there isn't a layer in progress</li>
126			<li>if there already was a change to that node</li>
127			<li>if there is no node with that name</li>
128			<li>if the node is marked read-only in a lower layer</li>
129			<li>if the name is not a valid node name</li>
130			<li>if the attributes are not valid for the node</li>
131            </ul>
132            <p><em>Not every implementation can detect each condition</em></p>
133
134		@throws com::sun::star::lang::WrappedTargetException
135			if an error occurs processing the event.
136
137		@see com::sun::star::configuration::backend::NodeAttribute
138	 */
139	void overrideNode( [in] string aName,
140					   [in] short  aAttributes,
141                       [in] boolean bClear )
142			raises( MalformedDataException,
143                    com::sun::star::lang::WrappedTargetException );
144	//-------------------------------------------------------------------------
145
146	/** receives notification that a new item is started.
147
148		<p> The current node must be a set and
149			a preexisting item (if any) must be removeable.
150		</p>
151		<p> The new item will be created from the default template
152			of the set.
153		</p>
154		<p> Subsequent calls describe the difference from the template
155			of properties and members or items of the node until
156			a matching call to <member>XLayerHandler::endNode()</member>
157            is encountered.
158		</p>
159
160		@param aName
161			specifies the name of the item.
162
163		@param aAttributes
164			specifies attribute values to be applied to the new node.
165
166			<p> The value is a combination of
167				<type>NodeAttribute</type> flags.  Note that
168                <member>NodeAttribute::FUSE</member> has an impact on the
169                semantics of this method.
170			</p>
171
172		@throws com::sun::star::configuration::backend::MalformedDataException
173            <ul>
174			<li>if there isn't a set node in progress currently</li>
175			<li>if there already was a change to a node of that name</li>
176			<li>if the template for the new node is not found</li>
177			<li>if an item of that name on a lower layer is not removeable</li>
178			<li>if the name is not a valid item name</li>
179			<li>if the attributes are not valid for the node</li>
180            </ul>
181            <p><em>Not every implementation can detect each condition</em></p>
182
183		@throws com::sun::star::lang::WrappedTargetException
184			if an error occurs processing the event.
185
186		@see com::sun::star::configuration::backend::NodeAttribute
187	 */
188	void addOrReplaceNode(	[in] string aName,
189							[in] short  aAttributes )
190			raises( MalformedDataException,
191                    com::sun::star::lang::WrappedTargetException );
192	//-------------------------------------------------------------------------
193
194	/** receives notification that a new item based on a particular template
195		is started.
196
197		<p> The current node must be a set and
198			a preexisting item (if any) must be removeable.
199		</p>
200		<p> Subsequent calls describe the difference from the template
201			of properties and members or items of the node until
202			a matching call to <member>XLayerHandler::endNode()</member>
203            is encountered.
204		</p>
205
206		@param aName
207			specifies the name of the item.
208
209		@param aTemplate
210			specifies the template to use for the new node
211
212		@param aAttributes
213			specifies attribute values to be applied to the new node.
214
215			<p> The value is a combination of
216				<type>NodeAttribute</type> flags.  Note that
217                <member>NodeAttribute::FUSE</member> has an impact on the
218                semantics of this method.
219			</p>
220
221		@throws com::sun::star::configuration::backend::MalformedDataException
222            <ul>
223			<li>if there isn't a set node in progress currently</li>
224			<li>if there already was a change to a node of that name</li>
225			<li>if the template for the new node is not found</li>
226			<li>if the template is not a valid item type for the containing set</li>
227			<li>if an item of that name on a lower layer is not removeable</li>
228			<li>if the name is not a valid item name</li>
229			<li>if the attributes are not valid for the node</li>
230            </ul>
231            <p><em>Not every implementation can detect each condition</em></p>
232
233		@throws com::sun::star::lang::WrappedTargetException
234			if an error occurs processing the event.
235
236		@see com::sun::star::configuration::backend::NodeAttribute
237	 */
238	void addOrReplaceNodeFromTemplate(	[in] string aName,
239										[in] TemplateIdentifier aTemplate,
240										[in] short  aAttributes )
241			raises( MalformedDataException,
242                    com::sun::star::lang::WrappedTargetException );
243	//-------------------------------------------------------------------------
244
245	/** receives notification that a node description is complete.
246
247		<p> Must match the last open call to
248			<member>XLayerHandler::overrideNode()</member>,
249			<member>XLayerHandler::addOrReplaceNode()</member> or
250			<member>XLayerHandler::addOrReplaceNodeFromTemplate()</member>.
251		</p>
252
253		@throws com::sun::star::configuration::backend::MalformedDataException
254            <ul>
255			<li>if invalid data is detected in the node</li>
256			<li>if no node is started at all</li>
257            </ul>
258            <p><em>Not every implementation can detect each condition</em></p>
259
260		@throws com::sun::star::lang::WrappedTargetException
261			if an error occurs processing the event.
262	 */
263	void endNode(  )
264			raises( MalformedDataException,
265                    com::sun::star::lang::WrappedTargetException );
266	//-------------------------------------------------------------------------
267
268	/** receives notification that a node is dropped from a set.
269
270		<p> The current node must be a set and
271			the item must be removeable.
272		</p>
273
274		@param aName
275			specifies the name of the node.
276
277		@throws com::sun::star::configuration::backend::MalformedDataException
278            <ul>
279			<li>if there isn't a set node in progress currently</li>
280			<li>if there already was a change to a node of that name</li>
281			<li>if there is no item with that name</li>
282			<li>if the item is not removeable</li>
283			<li>if the name is not a valid node name</li>
284            </ul>
285            <p><em>Not every implementation can detect each condition</em></p>
286
287		@throws com::sun::star::lang::WrappedTargetException
288			if an error occurs processing the event.
289	 */
290	void dropNode( [in] string aName )
291			raises( MalformedDataException,
292                    com::sun::star::lang::WrappedTargetException );
293	//-------------------------------------------------------------------------
294
295	/** receives notification that an existing property is modified.
296
297		<p> Subsequent calls describe new value(s) for the property until a
298            matching call to <member>XLayerHandler::endProperty()</member>
299            is encountered.
300		</p>
301
302		@param aName
303			specifies the name of the property.
304
305		@param aAttributes
306			specifies the new attributes of the property.
307
308			<p> The value is a combination of
309				<type>NodeAttribute</type> flags.
310			</p>
311			<p>	The attributes are combined cumulatively with those
312                set on lower layers.
313			</p>
314
315		@param aType
316			specifies the type of the property.
317
318			<p> This must be the same type as is already defined in the schema
319                or lower layers, unless the previous type was unspecified
320                (as indicated by
321                <const scope="com::sun::star::uno">TypeClass::ANY</const>.)
322			</p>
323			<p> A <void/> type indicates that the type is unspecified
324                in this layer.
325                In this case any subsequent value may be of a generic type
326                (e.g. <atom>string</atom> or - for list values -
327                <atom dim="[]">string</atom>.) Such values may be
328                converted to the type defined in the schema by
329                the implementation.
330			</p>
331
332		@param bClear
333			if <TRUE/>, specifies that the property should be cleared to an empty
334            state by discarding all values from lower layers prior
335            to applying the overrides.
336
337		@throws com::sun::star::configuration::backend::MalformedDataException
338            <ul>
339			<li>if there isn't a group or extensible node in progress currently</li>
340			<li>if there already was a change to a property of that name</li>
341			<li>if there is no property with that name</li>
342			<li>if the property is read-only</li>
343			<li>if the type does not match the type of the property</li>
344            <li>if a type is missing and cannot be determined otherwise</li>
345			<li>if the name is not a valid property name</li>
346			<li>if the attributes are not valid for the property</li>
347            </ul>
348            <p><em>Not every implementation can detect each condition</em></p>
349
350		@throws com::sun::star::lang::WrappedTargetException
351			if an error occurs processing the event.
352
353		@see com::sun::star::configuration::backend::NodeAttribute
354	 */
355	void overrideProperty(  [in] string aName,
356			 			    [in] short aAttributes,
357					        [in] type aType,
358                            [in] boolean bClear )
359			raises( MalformedDataException,
360                    com::sun::star::lang::WrappedTargetException );
361
362	//-------------------------------------------------------------------------
363
364	/** receives notification that the value of the current property
365        is overridden. .
366
367		@param aValue
368			specifies the new value of the property.
369
370			<p> The value must match the type of the current property.
371				If the property does not have the
372				<const>SchemaAttribute::REQUIRED</const> flag set,
373				the value can be <void/>.
374			</p>
375			<p> If the current property is localized, this value applies
376                to the default locale.
377			</p>
378
379		@throws com::sun::star::configuration::backend::MalformedDataException
380            <ul>
381			<li>if there isn't a property in progress currently</li>
382			<li>if there already was a change to the value of that property</li>
383			<li>if the value does not have the proper type</li>
384			<li>if the value is not valid for the property</li>
385            </ul>
386            <p><em>Not every implementation can detect each condition</em></p>
387
388		@throws com::sun::star::lang::WrappedTargetException
389			if an error occurs processing the event.
390
391		@see com::sun::star::configuration::backend::NodeAttribute
392	 */
393	void setPropertyValue(	[in] any aValue )
394			raises( MalformedDataException,
395                    com::sun::star::lang::WrappedTargetException );
396
397	//-------------------------------------------------------------------------
398
399	/** receives notification that the value of the current localized property
400        is overridden for a specific locale .
401
402		@param aValue
403			specifies the new value of the property.
404
405			<p> The value must match the type of the current property.
406				If the property does not have the
407				<const>SchemaAttribute::REQUIRED</const> flag set,
408				the value can be <void/>.
409			</p>
410
411		@param aLocale
412			specifies the locale this value should apply to.
413
414		@throws com::sun::star::configuration::backend::MalformedDataException
415            <ul>
416			<li>if there isn't a property in progress currently</li>
417			<li>if the current property isn't localized</li>
418			<li>if there already was a change to the property for that locale</li>
419			<li>if the value does not have the proper type</li>
420			<li>if the value is not valid for the property</li>
421			<li>if the locale is not a valid locale</li>
422            </ul>
423            <p><em>Not every implementation can detect each condition</em></p>
424
425		@throws com::sun::star::lang::WrappedTargetException
426			if an error occurs processing the event.
427
428		@see com::sun::star::configuration::backend::NodeAttribute
429	 */
430	void setPropertyValueForLocale([in] any aValue,
431			 					        [in] string aLocale )
432			raises( MalformedDataException,
433                    com::sun::star::lang::WrappedTargetException );
434
435	//-------------------------------------------------------------------------
436
437	/** receives notification that a property description is complete.
438
439		<p> Must match an open call to
440			<member>XLayerHandler::overrideProperty()</member>,
441		</p>
442
443		@throws com::sun::star::configuration::backend::MalformedDataException
444            <ul>
445			<li>if invalid data is detected in the property</li>
446			<li>if no property is started at all</li>
447            </ul>
448            <p><em>Not every implementation can detect each condition</em></p>
449
450		@throws com::sun::star::lang::WrappedTargetException
451			if an error occurs processing the event.
452	 */
453	void endProperty(  )
454			raises( MalformedDataException,
455                    com::sun::star::lang::WrappedTargetException );
456	//-------------------------------------------------------------------------
457
458	/** receives notification that a property having a <void/> value is added
459        to the current node.
460
461		<p> The current node must be extensible.
462		</p>
463
464		@param aName
465			specifies the name of the new property.
466
467		@param aAttributes
468			specifies the attributes of the new property.
469
470			<p> The value is a combination of
471				<type>NodeAttribute</type> flags and may also contain the
472				<const>SchemaAttribute::REQUIRED</const> flag.
473			</p>
474			<p>	<const>NodeAttribute::MANDATORY</const> need not be set,
475				as dynamically added properties always are mandatory
476				in subsequent layers.
477			</p>
478
479		@param aType
480			specifies the type of the new property.
481
482		@throws com::sun::star::configuration::backend::MalformedDataException
483            <ul>
484			<li>if there isn't an extensible node in progress currently</li>
485			<li>if a property with that name already exists</li>
486			<li>if the specified type is not allowed for a property</li>
487			<li>if the name is not a valid property name</li>
488			<li><li>if the attributes are not valid for the property</li>
489            </ul>
490            <p><em>Not every implementation can detect each condition</em></p>
491
492		@throws com::sun::star::lang::WrappedTargetException
493			if an error occurs processing the event.
494
495		@see com::sun::star::configuration::backend::SchemaAttribute
496	 */
497	void addProperty(   [in] string aName,
498			 		    [in] short aAttributes,
499					    [in] type aType )
500			raises( MalformedDataException,
501                    com::sun::star::lang::WrappedTargetException );
502
503	//-------------------------------------------------------------------------
504
505	/** receives notification that a property having a non-<void/> value
506		is added to the current node.
507
508		<p> The current node must be extensible.
509		</p>
510
511		@param aName
512			specifies the name of the new property.
513
514		@param aAttributes
515			specifies the attributes of the new property.
516
517			<p> The value is a combination of
518				<type>NodeAttribute</type> flags and may also contain the
519				<const>SchemaAttribute::REQUIRED</const> flag.
520			</p>
521			</p>
522			<p>	<const>NodeAttribute::MANDATORY</const> need not be set,
523				as dynamic properties always are mandatory
524				in subsequent layers.
525			</p>
526
527		@param aValue
528			specifies the value of the new property.
529
530			<p> The value also determines the type.
531				Therefore the value must not be <void/>.
532			</p>
533
534		@throws com::sun::star::configuration::backend::MalformedDataException
535            <ul>
536			<li>if there isn't an extensible node in progress currently</li>
537			<li>if a property with that name already exists</li>
538			<li>if the type of the value is not an allowed type
539			    or if the value is <void/></li>
540			<li>if the name is not a valid property name</li>
541			<li>if the value is not valid for the property</li>
542			<li>if the attributes are not valid for the property</li>
543            </ul>
544            <p><em>Not every implementation can detect each condition</em></p>
545
546		@throws com::sun::star::lang::WrappedTargetException
547			if an error occurs processing the event.
548
549		@see com::sun::star::configuration::backend::SchemaAttribute
550	 */
551	void addPropertyWithValue(  [in] string aName,
552			 					[in] short aAttributes,
553								[in] any aValue )
554			raises( MalformedDataException,
555                    com::sun::star::lang::WrappedTargetException );
556
557	//-------------------------------------------------------------------------
558};
559
560//=============================================================================
561
562}; }; }; }; };
563
564//=============================================================================
565
566#endif
567