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