offapi/com/sun/star/embed/XStorage.idl

   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  */
  94 published 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