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_XUpdateHandler_idl__ 24#define __com_sun_star_configuration_backend_XUpdateHandler_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#ifndef __com_sun_star_lang_IllegalAccessException_idl__ 43#include <com/sun/star/lang/IllegalAccessException.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 update or layer 53 as a sequence of events. 54 55 @since OpenOffice 1.1.2 56 */ 57published interface XUpdateHandler: ::com::sun::star::uno::XInterface 58{ 59 //------------------------------------------------------------------------- 60 61 /** receives notification that a update or description is started. 62 63 @throws com::sun::star::configuration::backend::MalformedDataException 64 if the update already was started 65 66 @throws com::sun::star::lang::IllegalAccessException 67 if the target layer is read-only 68 <p><em>Some implementations can only detect this when executing 69 <member>XUpdateHandler::endUpdate()</member></em> 70 </p> 71 72 @throws com::sun::star::lang::WrappedTargetException 73 if an error occurs processing the event. 74 */ 75 void startUpdate( ) 76 raises( MalformedDataException, 77 com::sun::star::lang::IllegalAccessException, 78 com::sun::star::lang::WrappedTargetException ); 79 //------------------------------------------------------------------------- 80 81 /** receives notification that the current update description is complete. 82 83 <p> Must match a previous call to <member>XUpdateHandler::startUpdate()</member>. 84 </p> 85 86 @throws com::sun::star::configuration::backend::MalformedDataException 87 <ul> 88 <li>if no update is started at all</li> 89 <li>if invalid data is detected in the update</li> 90 <li>if there is an unfinished subnode in progress</li> 91 <li>if the update tries to change read-only data</li> 92 </ul> 93 <p><em>Not every implementation can detect each condition</em></p> 94 95 @throws com::sun::star::lang::IllegalAccessException 96 if the target layer is read-only 97 98 @throws com::sun::star::lang::WrappedTargetException 99 if an error occurs processing the event. 100 */ 101 void endUpdate( ) 102 raises( MalformedDataException, 103 com::sun::star::lang::IllegalAccessException, 104 com::sun::star::lang::WrappedTargetException ); 105 //------------------------------------------------------------------------- 106 107 /** receives notification that a modification of a node is started. 108 109 <p> Subsequent calls describe changes to properties and items or 110 members of the node until a matching call to 111 <member>XUpdateHandler::endNode()</member> is encountered. 112 </p> 113 114 @param aName 115 specifies the name of the node. 116 117 @param aAttributes 118 specifies attribute values to be applied to the node in the 119 current layer. 120 121 <p> The value is a combination of 122 <type>NodeAttribute</type> flags. 123 </p> 124 <p> Only attributes which are selected in aAttributeMask 125 are changed. 126 </p> 127 128 @param aAttributeMask 129 specifies which attributes should be changed for the node. 130 131 <p> The value is a combination of 132 <type>NodeAttribute</type> flags. 133 </p> 134 135 @param bReset 136 if <TRUE/>, specifies that the node should be reset to its default 137 state as given by lower layers and the schema or template prior 138 to applying the changes. 139 140 @throws com::sun::star::configuration::backend::MalformedDataException 141 <ul> 142 <li>if there isn't an update in progress at all</li> 143 <li>if a node is not valid in this place</li> 144 <li>if there already was a change to that node</li> 145 <li>if there is no node with that name</li> 146 <li>if the node is read-only</li> 147 <li>if the name is not a valid node name</li> 148 <li>if the attributes or mask are not valid for the node</li> 149 </ul> 150 <p><em>Not every implementation can detect each condition</em></p> 151 152 @throws com::sun::star::lang::WrappedTargetException 153 if an error occurs processing the event. 154 155 @see com::sun::star::configuration::backend::NodeAttribute 156 */ 157 void modifyNode ( [in] string aName, 158 [in] short aAttributes, 159 [in] short aAttributeMask, 160 [in] boolean bReset ) 161 raises( MalformedDataException, 162 com::sun::star::lang::WrappedTargetException ); 163 //------------------------------------------------------------------------- 164 165 /** receives notification that a node is started as a new item. 166 167 <p> The current node must be a set and 168 a preexisting item (if any) must be removeable. 169 </p> 170 <p> The new item will be created from the default template 171 of the set. 172 </p> 173 <p> Subsequent calls describe the difference from the template 174 of properties, items or members of the node until a matching call 175 to <member>XUpdateHandler::endNode()</member> is encountered. 176 </p> 177 178 @param aName 179 specifies the name of the new item. 180 181 @param aAttributes 182 specifies attribute values to be applied to the new node. 183 184 <p> The value is a combination of 185 <type>NodeAttribute</type> flags. Note that 186 <member>NodeAttribute::FUSE</member> has an impact on the 187 semantics of this method. 188 </p> 189 190 @throws com::sun::star::configuration::backend::MalformedDataException 191 <ul> 192 <li>if there isn't a set node in progress currently</li> 193 <li>if there already was a change to an item of that name</li> 194 <li>if the template for the new node is not found</li> 195 <li>if an item of that name exists and is not removeable</li> 196 <li>if the name is not a valid item name</li> 197 <li>if the attributes are not valid for the node</li> 198 </ul> 199 <p><em>Not every implementation can detect each condition</em></p> 200 201 @throws com::sun::star::lang::WrappedTargetException 202 if an error occurs processing the event. 203 204 @see com::sun::star::configuration::backend::NodeAttribute 205 */ 206 void addOrReplaceNode ( [in] string aName, 207 [in] short aAttributes ) 208 raises( MalformedDataException, 209 com::sun::star::lang::WrappedTargetException ); 210 //------------------------------------------------------------------------- 211 212 /** receives notification that a node is started as a new item 213 based on a particular template. 214 215 <p> The current node must be a set and 216 a preexisting item (if any) must be removeable. 217 </p> 218 <p> Subsequent calls describe the difference from the template 219 of properties or members of the node until a matching call 220 to <member>XUpdateHandler::endNode()</member> is encountered. 221 </p> 222 223 @param aName 224 specifies the name of the item. 225 226 @param aTemplate 227 specifies the template to use for the new node 228 229 @param aAttributes 230 specifies attribute values to be applied to the new node. 231 232 <p> The value is a combination of 233 <type>NodeAttribute</type> flags. Note that 234 <member>NodeAttribute::FUSE</member> has an impact on the 235 semantics of this method. 236 </p> 237 238 @throws com::sun::star::configuration::backend::MalformedDataException 239 <ul> 240 <li>if there isn't a set node in progress currently</li> 241 <li>if there already was a change to an item of that name</li> 242 <li>if the template for the new node is not found</li> 243 <li>if an item of that name exists and is not removeable</li> 244 <li>if the name is not a valid item name</li> 245 <li>if the template is not a valid item type for the containing set</li> 246 <li>if the attributes are not valid for the node</li> 247 </ul> 248 <p><em>Not every implementation can detect each condition</em></p> 249 250 @throws com::sun::star::lang::WrappedTargetException 251 if an error occurs processing the event. 252 253 @see com::sun::star::configuration::backend::NodeAttribute 254 */ 255 void addOrReplaceNodeFromTemplate( [in] string aName, 256 [in] short aAttributes, 257 [in] TemplateIdentifier aTemplate ) 258 raises( MalformedDataException, 259 com::sun::star::lang::WrappedTargetException ); 260 //------------------------------------------------------------------------- 261 262 /** receives notification that a node modification is complete. 263 264 <p> Must match the last open call to 265 <member>XUpdateHandler::modifyNode()</member>, 266 <member>XUpdateHandler::addOrReplaceNode()</member> or 267 <member>XUpdateHandler::addOrReplaceNodeFromTemplate()</member>. 268 </p> 269 270 @throws com::sun::star::configuration::backend::MalformedDataException 271 <ul> 272 <li>if invalid data is detected in the node</li> 273 <li>if no node is started at all</li> 274 </ul> 275 <p><em>Not every implementation can detect each condition</em></p> 276 277 @throws com::sun::star::lang::WrappedTargetException 278 if an error occurs processing the event. 279 */ 280 void endNode( ) 281 raises( MalformedDataException, 282 com::sun::star::lang::WrappedTargetException ); 283 //------------------------------------------------------------------------- 284 285 /** receives notification that an item is to be dropped from a set. 286 287 <p> The current node must be a set and 288 the item must be removeable. 289 </p> 290 291 @param aName 292 specifies the name of the node. 293 294 @throws com::sun::star::configuration::backend::MalformedDataException 295 <ul> 296 <li>if there isn't a set node in progress currently</li> 297 <li>if there already was a change to a node of that name</li> 298 <li>if there is no item with that name</li> 299 <li>if the item is not removeable</li> 300 <li>if the name is not a valid node name</li> 301 </ul> 302 <p><em>Not every implementation can detect each condition</em></p> 303 304 @throws com::sun::star::lang::WrappedTargetException 305 if an error occurs processing the event. 306 */ 307 void removeNode( [in] string aName ) 308 raises( MalformedDataException, 309 com::sun::star::lang::WrappedTargetException ); 310 //------------------------------------------------------------------------- 311 312 /** receives notification that modification of an existing property is started. . 313 314 <p> Subsequent calls describe changes to the value(s) 315 of the property until a matching call to 316 <member>XUpdateHandler::endProperty()</member> is encountered. 317 </p> 318 319 @param aName 320 specifies the name of the property. 321 322 @param aAttributes 323 specifies new attributes of the property. 324 325 <p> The value is a combination of 326 <type>NodeAttribute</type> flags. 327 </p> 328 <p> Only attributes which are selected in aAttributeMask are changed. 329 </p> 330 <p> <const>NodeAttribute::MANDATORY</const> need not be set 331 and can't be removed, as dynamic properties always are mandatory 332 in subsequent layers. 333 </p> 334 335 @param aAttributeMask 336 specifies which attributes should be changed for the property. 337 338 <p> The value is a combination of 339 <type>NodeAttribute</type> flags. 340 </p> 341 342 @param aType 343 specifies the type of the property. 344 345 <p> A <void/> type can be used to signify that 346 the type is unknown and should not be recorded. 347 </p> 348 349 @throws com::sun::star::configuration::backend::MalformedDataException 350 <ul> 351 <li>if there isn't a group or extensible node in progress currently</li> 352 <li>if there already was a change to a property of that name</li> 353 <li>if there is no property with that name</li> 354 <li>if the property is read-only</li> 355 <li>if the name is not a valid property name</li> 356 <li>if the attributes are not valid for the property</li> 357 </ul> 358 <p><em>Not every implementation can detect each condition</em></p> 359 360 @throws com::sun::star::lang::WrappedTargetException 361 if an error occurs processing the event. 362 363 @see com::sun::star::configuration::backend::NodeAttribute 364 */ 365 void modifyProperty( [in] string aName, 366 [in] short aAttributes, 367 [in] short aAttributeMask, 368 [in] type aType ) 369 raises( MalformedDataException, 370 com::sun::star::lang::WrappedTargetException ); 371 //------------------------------------------------------------------------- 372 373 /** receives notification about a change to the value of 374 the current property. 375 376 @param aValue 377 specifies the new value of the property. 378 379 <p> The value must match the type of the existing property. 380 If the property does not have the 381 <const>SchemaAttribute::REQUIRED</const> flag set, 382 the value can be <void/>. 383 </p> 384 385 @throws com::sun::star::configuration::backend::MalformedDataException 386 <ul> 387 <li>if there isn't a property modification in progress currently</li> 388 <li>if there already was a change to this value</li> 389 <li>if the type of the value is not an allowed type</li> 390 <li>if the value is not valid for the property</li> 391 </ul> 392 <p><em>Not every implementation can detect each condition</em></p> 393 394 @throws com::sun::star::lang::WrappedTargetException 395 if an error occurs processing the event. 396 397 @see com::sun::star::configuration::backend::NodeAttribute 398 */ 399 void setPropertyValue( [in] any aValue ) 400 raises( MalformedDataException, 401 com::sun::star::lang::WrappedTargetException ); 402 //------------------------------------------------------------------------- 403 404 /** receives notification about a change to the value of 405 the current property for a specific locale. 406 407 @param aValue 408 specifies the new value of the property for the given locale. 409 410 <p> The value must match the type of the existing property. 411 If the property does not have the 412 <const>SchemaAttribute::REQUIRED</const> flag set, 413 the value can be <void/>. 414 </p> 415 416 @param aLocale 417 specifies the locale that the new value applies to. 418 419 @throws com::sun::star::configuration::backend::MalformedDataException 420 <ul> 421 <li>if there isn't a property modification in progress currently</li> 422 <li>if the property is not localizable</li> 423 <li>if there already was a change to this value</li> 424 <li>if the type of the value is not an allowed type</li> 425 <li>if the value is not valid for the property</li> 426 <li>if the locale is not a valid locale name</li> 427 </ul> 428 <p><em>Not every implementation can detect each condition</em></p> 429 430 @throws com::sun::star::lang::WrappedTargetException 431 if an error occurs processing the event. 432 433 @see com::sun::star::configuration::backend::NodeAttribute 434 */ 435 void setPropertyValueForLocale( [in] any aValue, [in] string aLocale ) 436 raises( MalformedDataException, 437 com::sun::star::lang::WrappedTargetException ); 438 //------------------------------------------------------------------------- 439 440 /** receives notification that the value of the current property 441 should be reset to its default. 442 443 @throws com::sun::star::configuration::backend::MalformedDataException 444 <ul> 445 <li>if there isn't a property modification in progress currently</li> 446 <li>if there already was a change to this value</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 @see com::sun::star::configuration::backend::NodeAttribute 454 */ 455 void resetPropertyValue( ) 456 raises( MalformedDataException, 457 com::sun::star::lang::WrappedTargetException ); 458 //------------------------------------------------------------------------- 459 460 /** receives notification that the value of the current property 461 for a specific locale should be reset to its default. 462 463 @param aLocale 464 specifies the locale the change applies to. 465 466 @throws com::sun::star::configuration::backend::MalformedDataException 467 <ul> 468 <li>if there isn't a property modification in progress currently</li> 469 <li>if the property is not localizable</li> 470 <li>if there already was a change to this value</li> 471 <li>if the locale is not a valid locale name</li> 472 </ul> 473 <p><em>Not every implementation can detect each condition</em></p> 474 475 @throws com::sun::star::lang::WrappedTargetException 476 if an error occurs processing the event. 477 478 @see com::sun::star::configuration::backend::NodeAttribute 479 */ 480 void resetPropertyValueForLocale( [in] string aLocale ) 481 raises( MalformedDataException, 482 com::sun::star::lang::WrappedTargetException ); 483 //------------------------------------------------------------------------- 484 485 /** receives notification that a property modification is complete. 486 487 <p> Must match the last open call to 488 <member>XUpdateHandler::modifyProperty()</member>. 489 </p> 490 491 @throws com::sun::star::configuration::backend::MalformedDataException 492 <ul> 493 <li>if invalid data is detected in the property</li> 494 <li>if no property is started at all</li> 495 </ul> 496 <p><em>Not every implementation can detect each condition</em></p> 497 498 @throws com::sun::star::lang::WrappedTargetException 499 if an error occurs processing the event. 500 */ 501 void endProperty( ) 502 raises( MalformedDataException, 503 com::sun::star::lang::WrappedTargetException ); 504 //------------------------------------------------------------------------- 505 506 /** receives notification that a property is reset to its default state. 507 508 @param aName 509 specifies the name of the property. 510 511 @throws com::sun::star::configuration::backend::MalformedDataException 512 <ul> 513 <li>if there isn't a group or extensible node in progress currently</li> 514 <li>if there already was a change to a property of that name</li> 515 <li>if there is no property with that name, or if the property 516 has no default</li> 517 <li>if the property is read-only</li> 518 <li>if the name is not a valid property name</li> 519 </ul> 520 <p><em>Not every implementation can detect each condition</em></p> 521 522 @throws com::sun::star::lang::WrappedTargetException 523 if an error occurs processing the event. 524 525 @see com::sun::star::configuration::backend::NodeAttribute 526 */ 527 void resetProperty( [in] string aName ) 528 raises( MalformedDataException, 529 com::sun::star::lang::WrappedTargetException ); 530 //------------------------------------------------------------------------- 531 532 /** receives notification that a property having a value of <void/> 533 is added to the current node. 534 535 <p> The current node must be extensible and 536 a preexisting property (if any) must be 537 removeable in this layer. 538 </p> 539 540 @param aName 541 specifies the name of the new property. 542 543 @param aAttributes 544 specifies the attributes of the new property. 545 546 <p> The value is a combination of 547 <type>NodeAttribute</type> flags and may also contain the 548 <const>SchemaAttribute::REQUIRED</const> flag. 549 </p> 550 </p> 551 <p> <const>NodeAttribute::MANDATORY</const> need not be set, 552 as dynamic properties always are mandatory 553 in subsequent layers. 554 </p> 555 556 @param aType 557 specifies the type of the new property. 558 559 @throws com::sun::star::configuration::backend::MalformedDataException 560 <ul> 561 <li>if there isn't a group or extensible node in progress currently</li> 562 <li>if there already was a change to a property of that name</li> 563 <li>if a property of that name exists and is not removeable</li> 564 <li>if the specified type is not allowed</li> 565 <li>if the name is not a valid property name</li> 566 <li>if the attributes are not valid for the property</li> 567 </ul> 568 <p><em>Not every implementation can detect each condition</em></p> 569 570 @throws com::sun::star::lang::WrappedTargetException 571 if an error occurs processing the event. 572 573 @see com::sun::star::configuration::backend::SchemaAttribute 574 */ 575 void addOrReplaceProperty( [in] string aName, 576 [in] short aAttributes, 577 [in] type aType ) 578 raises( MalformedDataException, 579 com::sun::star::lang::WrappedTargetException ); 580 //------------------------------------------------------------------------- 581 582 /** receives notification that a property having a non-<NULL/> value 583 is added to the current node. 584 585 <p> The current node must be extensible and 586 a preexisting property (if any) must be 587 removeable in this layer. 588 </p> 589 590 @param aName 591 specifies the name of the new property. 592 593 @param aAttributes 594 specifies the attributes of the new property. 595 596 <p> The value is a combination of 597 <type>NodeAttribute</type> flags and may also contain the 598 <const>SchemaAttribute::REQUIRED</const> flag. 599 </p> 600 </p> 601 <p> <const>NodeAttribute::MANDATORY</const> need not be set, 602 as dynamic properties always are mandatory 603 in subsequent layers. 604 </p> 605 606 @param aValue 607 specifies the value of the new property. 608 609 <p> The value also determines the type. 610 Therefore the value must not be <void/>. 611 </p> 612 613 @throws com::sun::star::configuration::backend::MalformedDataException 614 <ul> 615 <li>if there isn't a group or extensible node in progress currently</li> 616 <li>if there already was a change to a property of that name</li> 617 <li>if a property of that name exists and is not removeable</li> 618 <li>if the type of the value is not an allowed type, 619 or if the value is <void/></li> 620 <li>if the name is not a valid property name</li> 621 <li>if the attributes are not valid for the property</li> 622 </ul> 623 <p><em>Not every implementation can detect each condition</em></p> 624 625 @throws com::sun::star::lang::WrappedTargetException 626 if an error occurs processing the event. 627 628 @see com::sun::star::configuration::backend::SchemaAttribute 629 */ 630 void addOrReplacePropertyWithValue( [in] string aName, 631 [in] short aAttributes, 632 [in] any aValue ) 633 raises( MalformedDataException, 634 com::sun::star::lang::WrappedTargetException ); 635 //------------------------------------------------------------------------- 636 637 /** receives notification that a property is dropped from the current node. 638 639 <p>The current node must be extensible and the property removeable.</p> 640 641 @param aName 642 specifies the name of the property. 643 644 @throws com::sun::star::configuration::backend::MalformedDataException 645 <ul> 646 <li>if there isn't a group or extensible node in progress currently</li> 647 <li>if there is no property with that name</li> 648 <li>if the property is not removeable</li> 649 <li>if the name is not a valid node name</li> 650 </ul> 651 <p><em>Not every implementation can detect each condition</em></p> 652 653 @throws com::sun::star::lang::WrappedTargetException 654 if an error occurs processing the event. 655 */ 656 void removeProperty( [in] string aName ) 657 raises( MalformedDataException, 658 com::sun::star::lang::WrappedTargetException ); 659 //------------------------------------------------------------------------- 660 661}; 662 663//============================================================================= 664 665}; }; }; }; }; 666 667//============================================================================= 668 669#endif 670