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