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