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_XSchemaHandler_idl__
28#define __com_sun_star_configuration_backend_XSchemaHandler_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//=============================================================================
47
48module com { module sun { module star { module configuration { module backend {
49
50//=============================================================================
51
52/** receives a description of a configuration schema as a sequence of events.
53
54    @since OOo 1.1.2
55 */
56published interface XSchemaHandler: ::com::sun::star::uno::XInterface
57{
58	//-------------------------------------------------------------------------
59
60	/** receives notification that a schema description is started.
61
62		<p> The schema descrption may comprise components templates or both.
63		</p>
64
65		@throws com::sun::star::configuration::backend::MalformedDataException
66			if a schema is already started (and has not been ended).
67
68		@throws com::sun::star::lang::WrappedTargetException
69			if an error occurs processing the event.
70	 */
71	void startSchema( )
72			raises( MalformedDataException,
73                    com::sun::star::lang::WrappedTargetException );
74	//-------------------------------------------------------------------------
75
76	/** receives notification that the current schema description is complete.
77
78		<p> Must match a previous call to <member>startSchema</member>.
79		</p>
80
81		@throws com::sun::star::configuration::backend::MalformedDataException
82			<ul>
83            <li>if invalid data is detected in the schema</li>
84			<li>if there is a unfinished component or template in progress</li>
85			<li>if no schema is started at all</li>
86            </ul>
87            <p><em>Not every implementation can detect each condition</em></p>
88
89		@throws com::sun::star::lang::WrappedTargetException
90			if an error occurs processing the event.
91	 */
92	void endSchema(  )
93			raises( MalformedDataException,
94                    com::sun::star::lang::WrappedTargetException );
95	//-------------------------------------------------------------------------
96
97	/** receives notification that the schema depends on templates
98		from a different component.
99
100		@param aName
101			specifies the name of the component.
102
103		@throws com::sun::star::configuration::backend::MalformedDataException
104			<ul>
105			<li>if there is a unfinished component or template in progress</li>
106			<li>if no schema is started at all</li>
107			<li>if the name is not a valid component name</li>
108			<li>if the requested component is not found</li>
109            </ul>
110            <p><em>Not every implementation can detect each condition</em></p>
111
112		@throws com::sun::star::lang::WrappedTargetException
113			if an error occurs processing the event.
114	 */
115	void importComponent( [in] string aName )
116			raises( MalformedDataException,
117                    com::sun::star::lang::WrappedTargetException );
118	//-------------------------------------------------------------------------
119
120	/** receives notification that a component description is started.
121
122		<p> Subsequent calls describe the schema of the component
123			until a matching call to <member>endComponent</member>
124			is encountered.
125		</p>
126
127		@param aName
128			specifies the name of the component.
129
130		@throws com::sun::star::configuration::backend::MalformedDataException
131			<ul>
132			<li>if there is a unfinished component or template in progress </li>
133			<li>if no schema is started at all </li>
134			<li>if there already is a component data tree of this name</li>
135			<li>if the name is not a valid component name</li>
136			<li>if the instance supports no component schemas (only templates)</li>
137            </ul>
138            <p><em>Not every implementation can detect each condition</em></p>
139
140		@throws com::sun::star::lang::WrappedTargetException
141			if an error occurs processing the event.
142	 */
143	void startComponent( [in] string aName )
144			raises( MalformedDataException,
145                    com::sun::star::lang::WrappedTargetException );
146	//-------------------------------------------------------------------------
147
148	/** receives notification that a component description is complete.
149
150		<p> Must match a previous call to <member>startComponent</member>.
151		</p>
152
153		@throws com::sun::star::configuration::backend::MalformedDataException
154			<ul>
155			<li>if invalid data is detected in the component<li>
156			<li>if there is a unfinished subnode in progress<li>
157			<li>if no component has been started at all<li>
158			<li>if the instance supports no component schemas (only templates)<li>
159            </ul>
160            <p><em>Not every implementation can detect each condition</em></p>
161
162		@throws com::sun::star::lang::WrappedTargetException
163			if an error occurs processing the event.
164	 */
165	void endComponent(  )
166			raises( MalformedDataException,
167                    com::sun::star::lang::WrappedTargetException );
168	//-------------------------------------------------------------------------
169
170	/** receives notification that a template description is started for a group.
171
172		<p> Subsequent calls describe the members and properties of the template
173			until a matching call to <member>endTemplate</member>
174			is encountered.
175		</p>
176
177		@param aTemplate
178			specifies the identity of the template.
179
180		@param aAttributes
181			specifies the attributes of the template.
182
183			<p> The value is a combination of
184				<type>SchemaAttribute</type> flags.
185			</p>
186			<p>	<const>SchemaAttribute::EXTENSIBLE</const> can be used
187				to describe a template for a node with an extensible
188				set of properties.
189			</p>
190
191		@throws com::sun::star::configuration::backend::MalformedDataException
192            <ul>
193			<li>if there is a unfinished component or template in progress</li>
194			<li>if no schema is started at all </li>
195			<li>if there already is a template with that identifier</li>
196			<li>if the name is not a valid template identifier </li>
197			<li>if the attributes are not valid for a group</li>
198			<li>if the instance supports no templates (only component schemas)</li>
199            </ul>
200            <p><em>Not every implementation can detect each condition</em></p>
201
202		@throws com::sun::star::lang::WrappedTargetException
203			if an error occurs processing the event.
204
205		@see com::sun::star::configuration::backend::SchemaAttribute
206	 */
207	void startGroupTemplate( [in] TemplateIdentifier aTemplate,
208							 [in] short  aAttributes  )
209			raises( MalformedDataException,
210                    com::sun::star::lang::WrappedTargetException );
211	//-------------------------------------------------------------------------
212
213	/** receives notification that a template description is started for a set.
214
215		<p> Subsequent calls describe the members and properties of the template
216			until a matching call to <member>endTemplate</member>
217			is encountered.
218		</p>
219
220		@param aTemplate
221			specifies the identity of the template.
222
223		@param aAttributes
224			specifies the attributes of the template.
225
226			<p> The value is a combination of
227				<type>SchemaAttribute</type> flags.
228			</p>
229			<p>	<const>SchemaAttribute::EXTENSIBLE</const> can be used
230				to describe a template for a node with an extensible
231				set of properties.
232			</p>
233
234		@param aItemType
235			specifies the (default) template for set items.
236
237		@throws com::sun::star::configuration::backend::MalformedDataException
238            <ul>
239			<li>if there is a unfinished component or template in progress</li>
240			<li>if no schema is started at all </li>
241			<li>if there already is a template with that identifier</li>
242			<li>if the item-type template is not found</li>
243			<li>if the name or item-type are not valid template identifiers </li>
244			<li>if the attributes are not valid for a set</li>
245			<li>if the instance supports no templates (only component schemas).</li>
246            </ul>
247            <p><em>Not every implementation can detect each condition</em></p>
248
249		@throws com::sun::star::lang::WrappedTargetException
250			if an error occurs processing the event.
251
252		@see com::sun::star::configuration::backend::SchemaAttribute
253	 */
254	void startSetTemplate(	[in] TemplateIdentifier aTemplate,
255							[in] short  aAttributes,
256							[in] TemplateIdentifier aItemType  )
257			raises( MalformedDataException,
258                    com::sun::star::lang::WrappedTargetException );
259	//-------------------------------------------------------------------------
260
261	/** receives notification that a template description is complete.
262
263		<p> Must match a previous call to <member>startGroupTemplate</member>
264			or <member>startSetTemplate</member>.
265		</p>
266
267		@throws com::sun::star::configuration::backend::MalformedDataException
268            <ul>
269			<li>if invalid data is detected in the template</li>
270			<li>if there is a unfinished subnode in progress</li>
271			<li>if no template has been started at all</li>
272			<li>if the instance supports no templates (only component schemas)</li>
273            </ul>
274            <p><em>Not every implementation can detect each condition</em></p>
275
276		@throws com::sun::star::lang::WrappedTargetException
277			if an error occurs processing the event.
278	 */
279	void endTemplate(  )
280			raises( MalformedDataException,
281                    com::sun::star::lang::WrappedTargetException );
282	//-------------------------------------------------------------------------
283
284	/** receives notification that a group description is started.
285
286		<p> Subsequent calls describe the members and properties of the group
287			until a matching call to <member>endNode</member>
288			is encountered.
289		</p>
290
291		@param aName
292			specifies the name of the group.
293
294		@param aAttributes
295			specifies the attributes of the node.
296
297			<p> The value is a combination of
298				<type>SchemaAttribute</type> flags.
299			</p>
300			<p>	<const>SchemaAttribute::EXTENSIBLE</const> can be used
301				to describe a group with an extensible set of properties.
302			</p>
303
304		@throws com::sun::star::configuration::backend::MalformedDataException
305            <ul>
306			<li>if there isn't a group node in progress currently</li>
307			<li>if there already is a node with that name</li>
308			<li>if the name is not a valid node name</li>
309			<li>if the attributes are not valid for a group</li>
310            </ul>
311            <p><em>Not every implementation can detect each condition</em></p>
312
313		@throws com::sun::star::lang::WrappedTargetException
314			if an error occurs processing the event.
315
316		@see com::sun::star::configuration::backend::SchemaAttribute
317	 */
318	void startGroup( [in] string aName,
319					 [in] short  aAttributes )
320			raises( MalformedDataException,
321                    com::sun::star::lang::WrappedTargetException );
322	//-------------------------------------------------------------------------
323
324	/** receives notification that a set description is started.
325
326		<p> Subsequent calls describe the item-types and properties of the set
327			until a matching call to <member>endNode</member>
328			is encountered.
329		</p>
330
331		@param aName
332			specifies the name of the set.
333
334		@param aAttributes
335			specifies the attributes of the node.
336
337			<p> The value is a combination of
338				<type>SchemaAttribute</type> flags.
339			</p>
340			<p>	<const>SchemaAttribute::EXTENSIBLE</const> can be used
341				to describe a set with an extensible set of properties.
342			</p>
343
344		@param aItemType
345			specifies the (default) template for set items.
346
347		@throws com::sun::star::configuration::backend::MalformedDataException
348            <ul>
349			<li>if there isn't a group node in progress currently</li>
350			<li>if there already is a node with that name</li>
351			<li>if the item-type template is not found</li>
352			<li>if the name is not a valid node name</li>
353			<li>if the item-type is not a valid template identifier</li>
354			<li>if the attributes are not valid for a set</li>
355            </ul>
356            <p><em>Not every implementation can detect each condition</em></p>
357
358		@throws com::sun::star::lang::WrappedTargetException
359			if an error occurs processing the event.
360
361		@see com::sun::star::configuration::backend::SchemaAttribute
362	 */
363	void startSet( [in] string aName,
364				   [in] short  aAttributes,
365				   [in] TemplateIdentifier aItemType )
366			raises( MalformedDataException,
367                    com::sun::star::lang::WrappedTargetException );
368	//-------------------------------------------------------------------------
369
370	/** receives notification that a node description is complete.
371
372		<p> Must match the last open call to <member>startGroup</member>
373			or <member>startSet</member>.
374		</p>
375
376		@throws com::sun::star::configuration::backend::MalformedDataException
377            <ul>
378			<li>if the name is not a the name of the node in progress</li>
379			<li>if invalid data is detected in the node</li>
380			<li>if no node has been started at all</li>
381            </ul>
382            <p><em>Not every implementation can detect each condition</em></p>
383
384		@throws com::sun::star::lang::WrappedTargetException
385			if an error occurs processing the event.
386	 */
387	void endNode(  )
388			raises( MalformedDataException,
389                    com::sun::star::lang::WrappedTargetException );
390	//-------------------------------------------------------------------------
391
392	/** receives notification that a property is added to the current node.
393
394		<p>	The property will have a default value of <NULL/>
395			(unless it is <const>SchemaAttribute::REQUIRED</const>).
396		</p>
397
398		@param aName
399			specifies the name of the new property.
400
401		@param aAttributes
402			specifies the attributes of the new property.
403
404			<p> The value is a combination of
405				<type>SchemaAttribute</type> flags.
406			</p>
407
408		@param aType
409			specifies the type of the new property.
410
411		@throws com::sun::star::configuration::backend::MalformedDataException
412            <ul>
413			<li>if there isn't a group or extensible node in progress currently</li>
414			<li>if a property with the same name already exists</li>
415			<li>if the specified type is not allowed</li>
416			<li>if the name is not a valid property name</li>
417			<li>if the attributes are not valid for a property</li>
418            </ul>
419            <p><em>Not every implementation can detect each condition</em></p>
420
421		@throws com::sun::star::lang::WrappedTargetException
422			if an error occurs processing the event.
423
424		@see com::sun::star::configuration::backend::SchemaAttribute
425	 */
426	void addProperty( [in] string aName,
427			 		  [in] short aAttributes,
428					  [in] type aType )
429			raises( MalformedDataException,
430                    com::sun::star::lang::WrappedTargetException );
431
432	//-------------------------------------------------------------------------
433
434	/** receives notification that a property having a default value
435		is added to the current node.
436
437		@param aName
438			specifies the name of the new property.
439
440		@param aAttributes
441			specifies the attributes of the new property.
442
443			<p> The value is a combination of
444				<type>SchemaAttribute</type> flags.
445			</p>
446
447		@param aDefaultValue
448			specifies the value of the new property.
449
450			<p> The value also determines the type.
451				Therefore the value must not be <void/>.
452			</p>
453
454		@throws com::sun::star::configuration::backend::MalformedDataException
455            <ul>
456			<li>if there isn't a group or extensible node in progress currently</li>
457			<li>if a property with the same name already exists</li>
458			<li>if the type of the default value is not an allowed type,
459			    or if the default value is <void/></li>
460			<li>if the name is not a valid property name</li>
461			<li>if the attributes are not valid for a property</li>
462            </ul>
463            <p><em>Not every implementation can detect each condition</em></p>
464
465		@throws com::sun::star::lang::WrappedTargetException
466			if an error occurs processing the event.
467
468		@see com::sun::star::configuration::backend::SchemaAttribute
469	 */
470	void addPropertyWithDefault( [in] string aName,
471			 					 [in] short aAttributes,
472								 [in] any aDefaultValue )
473			raises( MalformedDataException,
474                    com::sun::star::lang::WrappedTargetException );
475
476	//-------------------------------------------------------------------------
477
478	/** receives notification that the current group has a child node
479		that is an instance of a specified template.
480
481		@param aName
482			specifies the name of the new node.
483
484		@param aTemplate
485			specifies a template that describes the new node.
486
487		@throws com::sun::star::configuration::backend::MalformedDataException
488            <ul>
489			<li>if there isn't a group node in progress currently</li>
490			<li>if there already is a node with that name</li>
491			<li>if the template is not found</li>
492			<li>if the name or template name are not valid</li>
493            </ul>
494            <p><em>Not every implementation can detect each condition</em></p>
495
496		@throws com::sun::star::lang::WrappedTargetException
497			if an error occurs processing the event.
498	 */
499	void addInstance( [in] string aName,
500			 		  [in] TemplateIdentifier aTemplate )
501			raises( MalformedDataException,
502                    com::sun::star::lang::WrappedTargetException );
503
504	//-------------------------------------------------------------------------
505
506	/** receives notification that the current set can contain items
507		that are instances of a specified template.
508
509		@param aItemType
510			specifies a template that is accepted as valid item type
511			for the current set node.
512
513		@throws com::sun::star::configuration::backend::MalformedDataException
514            <ul>
515			<li>if there isn't a set node in progress currently</li>
516			<li>if the template is not found</li>
517			<li>if the name is not a valid template name</li>
518            </ul>
519            <p><em>Not every implementation can detect each condition</em></p>
520
521		@throws com::sun::star::lang::WrappedTargetException
522			if an error occurs processing the event.
523	 */
524	void addItemType( [in] TemplateIdentifier aItemType )
525			raises( MalformedDataException,
526                    com::sun::star::lang::WrappedTargetException );
527
528	//-------------------------------------------------------------------------
529
530};
531
532//=============================================================================
533
534}; }; }; }; };
535
536//=============================================================================
537
538#endif
539