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