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

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