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