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_embed_XStorage_idl__ 24#define __com_sun_star_embed_XStorage_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_io_XStream_idl__ 31#include <com/sun/star/io/XStream.idl> 32#endif 33 34#ifndef __com_sun_star_io_XInputStream_idl__ 35#include <com/sun/star/io/XInputStream.idl> 36#endif 37 38#ifndef __com_sun_star_io_IOException_idl__ 39#include <com/sun/star/io/IOException.idl> 40#endif 41 42#ifndef __com_sun_star_lang_XComponent_idl__ 43#include <com/sun/star/lang/XComponent.idl> 44#endif 45 46#ifndef __com_sun_star_lang_IllegalArgumentException_idl__ 47#include <com/sun/star/lang/IllegalArgumentException.idl> 48#endif 49 50#ifndef __com_sun_star_embed_StorageWrappedTargetException_idl__ 51#include <com/sun/star/embed/StorageWrappedTargetException.idl> 52#endif 53 54#ifndef __com_sun_star_embed_InvalidStorageException_idl__ 55#include <com/sun/star/embed/InvalidStorageException.idl> 56#endif 57 58#ifndef __com_sun_star_packages_WrongPasswordException_idl__ 59#include <com/sun/star/packages/WrongPasswordException.idl> 60#endif 61 62#ifndef __com_sun_star_container_XNameAccess_idl__ 63#include <com/sun/star/container/XNameAccess.idl> 64#endif 65 66#ifndef __com_sun_star_container_NoSuchElementException_idl__ 67#include <com/sun/star/container/NoSuchElementException.idl> 68#endif 69 70#ifndef __com_sun_star_container_ElementExistException_idl__ 71#include <com/sun/star/container/ElementExistException.idl> 72#endif 73 74#ifndef __com_sun_star_packages_NoEncryptionException_idl__ 75#include <com/sun/star/packages/NoEncryptionException.idl> 76#endif 77 78#ifndef __com_sun_star_packages_NoRawFormatException_idl__ 79#include <com/sun/star/packages/NoRawFormatException.idl> 80#endif 81 82 83//============================================================================ 84 85 module com { module sun { module star { module embed { 86 87//============================================================================ 88/** This interface represents main storage functionality. 89 */ 90published interface XStorage 91{ 92 // INTERFACES 93 // 94 // ----------------------------------------------------------------------- 95 /** allows to get list of child elements and to check if an element with a 96 specified name exists in a storage. 97 98 <p> 99 It is also possible to use this interface to get read access to 100 a child element by 101 <method scope="com::sun::star::container">XNameAccess::getByName</method> 102 call. But the recommended way is to use <type>XStorage</type> 103 interface for this purpose. 104 </p> 105 */ 106 interface ::com::sun::star::container::XNameAccess; 107 108 // ----------------------------------------------------------------------- 109 /** allows to controll and track lifetime of the storage. 110 111 <p> 112 In case a storage is disposed any call to it's methods should result 113 in <type scope="com::sun::star::lang">DisposedException</type>. 114 </p> 115 */ 116 interface ::com::sun::star::lang::XComponent; 117 118 119 // METHODS 120 // 121 // ----------------------------------------------------------------------- 122 /** allows to copy current storage to another one 123 124 <p> 125 The destination storage contents are overwritten. 126 After the successful copying the target storage is automatically 127 commited if it implements transacted access. 128 </p> 129 130 @param xDest 131 a destination storage this storage must be copied to. 132 133 @throws ::com::sun::star::embed::InvalidStorageException 134 this storage is in invalid state for any reason 135 136 @throws ::com::sun::star::lang::IllegalArgumentException 137 an illegal argument is provided 138 139 @throws ::com::sun::star::io::IOException 140 in case of io errors during copying 141 142 @throws ::com::sun::star::embed::StorageWrappedTargetException 143 wraps other exception acquired during copying 144 */ 145 void copyToStorage( [in] XStorage xDest ) 146 raises( ::com::sun::star::embed::InvalidStorageException, 147 ::com::sun::star::lang::IllegalArgumentException, 148 ::com::sun::star::io::IOException, 149 ::com::sun::star::embed::StorageWrappedTargetException ); 150 151 // ----------------------------------------------------------------------- 152 /** allows to get access to a child stream of the storage. 153 154 <p> 155 In case the stream is open in readonly mode the 156 <method scope="com::sun::star::io">XStream::getOutputStream</method> 157 method will return an empty reference. 158 </p> 159 160 @param sStreamName 161 the name of the substream that should be open 162 163 @param nOpenMode 164 a mode the stream should be open in, 165 can be a combination of <type>ElementModes</type> values 166 167 @throws ::com::sun::star::embed::InvalidStorageException 168 this storage is in invalid state for any reason 169 170 @throws ::com::sun::star::lang::IllegalArgumentException 171 one of provided arguments is illegal 172 173 @throws ::com::sun::star::packages::WrongPasswordException 174 the provided password is wrong 175 176 @throws ::com::sun::star::io::IOException 177 in case of io errors during stream opening 178 179 @throws ::com::sun::star::embed::StorageWrappedTargetException 180 wraps other exceptions 181 */ 182 ::com::sun::star::io::XStream openStreamElement( 183 [in] string sStreamName, 184 [in] long nOpenMode ) 185 raises( ::com::sun::star::embed::InvalidStorageException, 186 ::com::sun::star::lang::IllegalArgumentException, 187 ::com::sun::star::packages::WrongPasswordException, 188 ::com::sun::star::io::IOException, 189 ::com::sun::star::embed::StorageWrappedTargetException ); 190 191 // ----------------------------------------------------------------------- 192 /** allows to get access to a child encrypted stream with password. 193 194 <p> 195 If storage does not allow any encryption this method will always throw 196 <type scope="com::sun::star::packages">NoEncryptionException</type>. 197 </p> 198 199 <p> 200 In case the stream is open in readonly mode the 201 <method scope="com::sun::star::io">XStream::getOutputStream</method> 202 method will return an empty reference. 203 </p> 204 205 @param sStreamName 206 the name of the substream that should be open 207 208 @param nOpenMode 209 a mode the stream should be open in, 210 can be a combination of <type>ElementModes</type> values 211 212 @param sPassword 213 this parameter allowes to specify a reading password for the 214 stream, the password must be a correct one, otherwise an 215 exception will be thrown 216 217 @throws ::com::sun::star::embed::InvalidStorageException 218 this storage is in invalid state for any reason 219 220 @throws ::com::sun::star::lang::IllegalArgumentException 221 one of provided arguments is illegal 222 223 @throws ::com::sun::star::packages::NoEncryptionException 224 the stream is not encrypted 225 226 @throws ::com::sun::star::packages::WrongPasswordException 227 the provided password is wrong 228 229 @throws ::com::sun::star::io::IOException 230 in case of io errors during stream opening 231 232 @throws ::com::sun::star::embed::StorageWrappedTargetException 233 wraps other exceptions 234 */ 235 ::com::sun::star::io::XStream openEncryptedStreamElement( 236 [in] string sStreamName, 237 [in] long nOpenMode, 238 [in] string sPassword ) 239 raises( ::com::sun::star::embed::InvalidStorageException, 240 ::com::sun::star::lang::IllegalArgumentException, 241 ::com::sun::star::packages::NoEncryptionException, 242 ::com::sun::star::packages::WrongPasswordException, 243 ::com::sun::star::io::IOException, 244 ::com::sun::star::embed::StorageWrappedTargetException ); 245 246 // ----------------------------------------------------------------------- 247 /** allows to get access to a child storage. 248 249 <p> 250 The opened substorage must support specified in 'nOpenMode' access 251 modes. It can support 'read' mode in addition. But any child element 252 can support one of those modes only in case this mode is supported by 253 parent storage. 254 </p> 255 256 @param sStorName 257 the name of the storage that should be open 258 259 @param nOpenMode 260 a mode the storage should be open in 261 262 @throws ::com::sun::star::embed::InvalidStorageException 263 this storage is in invalid state for any reason 264 265 @throws ::com::sun::star::lang::IllegalArgumentException 266 one of provided arguments is illegal 267 268 @throws ::com::sun::star::io::IOException 269 in case of io errors during stream opening 270 271 @throws ::com::sun::star::embed::StorageWrappedTargetException 272 wraps other exceptions 273 274 */ 275 XStorage openStorageElement( [in] string sStorName, 276 [in] long nOpenMode ) 277 raises( ::com::sun::star::embed::InvalidStorageException, 278 ::com::sun::star::lang::IllegalArgumentException, 279 ::com::sun::star::io::IOException, 280 ::com::sun::star::embed::StorageWrappedTargetException ); 281 282 // ----------------------------------------------------------------------- 283 /** allows to get readonly copy of a child stream of the storage. 284 285 <p> 286 The stream is open in readonly mode so the 287 <method scope="com::sun::star::io">XStream::getOutputStream</method> 288 method will return an empty reference. 289 </p> 290 291 @param sStreamName 292 the name of the substream that should be copied 293 294 @throws ::com::sun::star::embed::InvalidStorageException 295 this storage is in invalid state for any reason 296 297 @throws ::com::sun::star::lang::IllegalArgumentException 298 one of provided arguments is illegal 299 300 @throws ::com::sun::star::packages::WrongPasswordException 301 the provided password is wrong 302 303 @throws ::com::sun::star::io::IOException 304 in case of io errors during stream opening 305 306 @throws ::com::sun::star::embed::StorageWrappedTargetException 307 wraps other exceptions 308 */ 309 ::com::sun::star::io::XStream cloneStreamElement( [in] string sStreamName ) 310 raises( ::com::sun::star::embed::InvalidStorageException, 311 ::com::sun::star::lang::IllegalArgumentException, 312 ::com::sun::star::packages::WrongPasswordException, 313 ::com::sun::star::io::IOException, 314 ::com::sun::star::embed::StorageWrappedTargetException ); 315 316 // ----------------------------------------------------------------------- 317 /** allows to get readonly copy of a child encrypted stream with password. 318 319 <p> 320 If storage does not allow any encryption this method will always throw 321 <type scope="com::sun::star::packages">NoEncryptionException</type>. 322 </p> 323 324 <p> 325 The stream is open in readonly mode so the 326 <method scope="com::sun::star::io">XStream::getOutputStream</method> 327 method will return an empty reference. 328 </p> 329 330 <p> 331 This method allows to specify reading password for the child stream 332 explicitly. 333 </p> 334 335 @param sStreamName 336 the name of the substream that should be copied 337 338 @param sPassword 339 this parameter allowes to specify a reading password for the 340 stream, the password must be a correct one, otherwise an 341 exception will be thrown 342 343 @throws ::com::sun::star::embed::InvalidStorageException 344 this storage is in invalid state for any reason 345 346 @throws ::com::sun::star::lang::IllegalArgumentException 347 one of provided arguments is illegal 348 349 @throws ::com::sun::star::packages::NoEncryptionException 350 the stream is not encrypted 351 352 @throws ::com::sun::star::packages::WrongPasswordException 353 the provided password is wrong 354 355 @throws ::com::sun::star::io::IOException 356 in case of io errors during stream opening 357 358 @throws ::com::sun::star::embed::StorageWrappedTargetException 359 wraps other exceptions 360 */ 361 ::com::sun::star::io::XStream cloneEncryptedStreamElement( 362 [in] string sStreamName, 363 [in] string sPassword ) 364 raises( ::com::sun::star::embed::InvalidStorageException, 365 ::com::sun::star::lang::IllegalArgumentException, 366 ::com::sun::star::packages::NoEncryptionException, 367 ::com::sun::star::packages::WrongPasswordException, 368 ::com::sun::star::io::IOException, 369 ::com::sun::star::embed::StorageWrappedTargetException ); 370 371 // ----------------------------------------------------------------------- 372 /** allows to get copy of this storage at the state of it's last commit. 373 374 <p> 375 This method makes sence only for services implementations that allow 376 transaction in the storage. 377 </p> 378 379 @param xStorage 380 the target storage that will be filled in with copy. 381 382 @throws ::com::sun::star::embed::InvalidStorageException 383 this storage is in invalid state for any reason 384 385 @throws ::com::sun::star::lang::IllegalArgumentException 386 one of provided arguments is illegal 387 388 @throws ::com::sun::star::io::IOException 389 in case of io errors during copying 390 391 @throws ::com::sun::star::embed::StorageWrappedTargetException 392 wraps other exceptions 393 394 */ 395 void copyLastCommitTo( [in] XStorage xTargetStorage ) 396 raises( ::com::sun::star::embed::InvalidStorageException, 397 ::com::sun::star::lang::IllegalArgumentException, 398 ::com::sun::star::io::IOException, 399 ::com::sun::star::embed::StorageWrappedTargetException ); 400 401 // ----------------------------------------------------------------------- 402 /** allows to get copy of a child storage at the state of it's last commit. 403 404 <p> 405 This method makes sence only for services implementations that allow 406 transaction in the storage. 407 </p> 408 409 @param sStorName 410 the name of the storage that should be copied 411 412 @param xStorage 413 the target storage that will be filled in with copy 414 415 @throws ::com::sun::star::embed::InvalidStorageException 416 this storage is in invalid state for any reason 417 418 @throws ::com::sun::star::lang::IllegalArgumentException 419 one of provided arguments is illegal 420 421 @throws ::com::sun::star::io::IOException 422 in case of io errors during copying 423 424 @throws ::com::sun::star::embed::StorageWrappedTargetException 425 wraps other exceptions 426 427 */ 428 void copyStorageElementLastCommitTo( 429 [in] string sStorName, 430 [in] XStorage xTargetStorage ) 431 raises( ::com::sun::star::embed::InvalidStorageException, 432 ::com::sun::star::lang::IllegalArgumentException, 433 ::com::sun::star::io::IOException, 434 ::com::sun::star::embed::StorageWrappedTargetException ); 435 436 // ----------------------------------------------------------------------- 437 /** allows to check if an element is a child stream with specified name. 438 439 <p> 440 In case there is no child element with such name an exception will be 441 thrown. 442 </p> 443 444 @param sElementName 445 the name of the element to check 446 447 @returns 448 <TRUE/> in case the element is a stream 449 <FALSE/> - the element is a storage 450 451 @throws ::com::sun::star::container::NoSuchElementException 452 there is no element with such name 453 454 @throws ::com::sun::star::lang::IllegalArgumentException 455 an illegal argument is provided 456 457 @throws ::com::sun::star::embed::InvalidStorageException 458 this storage is in invalid state for any reason 459 460 */ 461 boolean isStreamElement( [in] string sElementName ) 462 raises( ::com::sun::star::container::NoSuchElementException, 463 ::com::sun::star::lang::IllegalArgumentException, 464 ::com::sun::star::embed::InvalidStorageException ); 465 466 467 // ----------------------------------------------------------------------- 468 /** allows to check if an element is a child storage with specified name. 469 470 <p> 471 In case there is no child element with such name an exception will be 472 thrown. 473 </p> 474 475 @param sElementName 476 the name of the element to check 477 478 @returns 479 <TRUE/> in case the element is a storage 480 <FALSE/> - the element is a stream 481 482 @throws ::com::sun::star::container::NoSuchElementException 483 there is no element with such name 484 485 @throws ::com::sun::star::lang::IllegalArgumentException 486 an illegal argument is provided 487 488 @throws ::com::sun::star::embed::InvalidStorageException 489 this storage is in invalid state for any reason 490 491 */ 492 boolean isStorageElement( [in] string sElementName ) 493 raises( ::com::sun::star::container::NoSuchElementException, 494 ::com::sun::star::lang::IllegalArgumentException, 495 ::com::sun::star::embed::InvalidStorageException ); 496 497 // ----------------------------------------------------------------------- 498 /** removes an element from a storage. 499 500 @param sElementName 501 the name of the element to remove 502 503 @throws ::com::sun::star::embed::InvalidStorageException 504 this storage is in invalid state for eny reason 505 506 @throws ::com::sun::star::lang::IllegalArgumentException 507 an illegal argument is provided 508 509 @throws ::com::sun::star::container::NoSuchElementException 510 there is no element with such name 511 512 @throws ::com::sun::star::io::IOException 513 in case of io errors during removing 514 515 @throws ::com::sun::star::embed::StorageWrappedTargetException 516 wraps other exceptions 517 518 */ 519 void removeElement( [in] string sElementName ) 520 raises( ::com::sun::star::embed::InvalidStorageException, 521 ::com::sun::star::lang::IllegalArgumentException, 522 ::com::sun::star::container::NoSuchElementException, 523 ::com::sun::star::io::IOException, 524 ::com::sun::star::embed::StorageWrappedTargetException ); 525 526 // ----------------------------------------------------------------------- 527 /** renames an element in a storage. 528 529 @param sElementName 530 the old name of the element to rename 531 532 @param sNewName 533 the new name of the element to rename 534 535 @throws ::com::sun::star::embed::InvalidStorageException 536 this storage is in invalid state for eny reason 537 538 @throws ::com::sun::star::lang::IllegalArgumentException 539 an illegal argument is provided 540 541 @throws ::com::sun::star::container::NoSuchElementException 542 there is no element with old name in this storage 543 544 @throws ::com::sun::star::container::ElementExistException 545 an element with new name already exists in this storage 546 547 @throws ::com::sun::star::io::IOException 548 in case of io errors during renaming 549 550 @throws ::com::sun::star::embed::StorageWrappedTargetException 551 wraps other exceptions 552 553 */ 554 void renameElement( [in] string sElementName, [in] string sNewName ) 555 raises( ::com::sun::star::embed::InvalidStorageException, 556 ::com::sun::star::lang::IllegalArgumentException, 557 ::com::sun::star::container::NoSuchElementException, 558 ::com::sun::star::container::ElementExistException, 559 ::com::sun::star::io::IOException, 560 ::com::sun::star::embed::StorageWrappedTargetException ); 561 562 // ----------------------------------------------------------------------- 563 /** allows to copy an entry from one storage to another. 564 565 <p> 566 If target element supports transacted mode it must be commited by this 567 method after successful copying. 568 </p> 569 570 @param sElementName 571 the name of the element in this storage 572 573 @param xDest 574 a destination storage 575 576 @param sNewName 577 the name of the result element in destination storage 578 579 @throws ::com::sun::star::embed::InvalidStorageException 580 this storage is in invalid state for eny reason 581 582 @throws ::com::sun::star::container::NoSuchElementException 583 there is no specified source element in this storage 584 585 @throws ::com::sun::star::container::ElementExistException 586 an element with specified destination name already exists in destination storage 587 588 @throws ::com::sun::star::io::IOException 589 in case of io errors during copying 590 591 @throws ::com::sun::star::embed::StorageWrappedTargetException 592 wraps other exceptions 593 594 */ 595 void copyElementTo( 596 [in] string sElementName, 597 [in] XStorage xDest, 598 [in] string sNewName ) 599 raises( ::com::sun::star::embed::InvalidStorageException, 600 ::com::sun::star::lang::IllegalArgumentException, 601 ::com::sun::star::container::NoSuchElementException, 602 ::com::sun::star::container::ElementExistException, 603 ::com::sun::star::io::IOException, 604 ::com::sun::star::embed::StorageWrappedTargetException ); 605 606 // ----------------------------------------------------------------------- 607 /** allows to move an entry from one storage to another. 608 609 <p> 610 If target element supports transacted mode it must be commited by this 611 method after successful moving. 612 </p> 613 614 @param sElementName 615 the name of the element in this storage 616 617 @param xDest 618 a destination storage 619 620 @param sNewName 621 the name of the result element in destination storage 622 623 @throws ::com::sun::star::embed::InvalidStorageException 624 this storage is in invalid state for eny reason 625 626 @throws ::com::sun::star::container::NoSuchElementException 627 there is no specified source element in this storage 628 629 @throws ::com::sun::star::container::ElementExistException 630 an element with specified destination name already exists in destination storage 631 632 @throws ::com::sun::star::io::IOException 633 in case of io errors during moving 634 635 @throws ::com::sun::star::embed::StorageWrappedTargetException 636 wraps other exceptions 637 638 */ 639 void moveElementTo( 640 [in] string sElementName, 641 [in] XStorage xDest, 642 [in] string sNewName ) 643 raises( ::com::sun::star::embed::InvalidStorageException, 644 ::com::sun::star::lang::IllegalArgumentException, 645 ::com::sun::star::container::NoSuchElementException, 646 ::com::sun::star::container::ElementExistException, 647 ::com::sun::star::io::IOException, 648 ::com::sun::star::embed::StorageWrappedTargetException ); 649 650}; 651 652//============================================================================ 653 654}; }; }; }; 655 656#endif 657 658