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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20
  21
  22  module com {  module sun {  module star {  module embed {
  23
  24 /** This interface represents main storage functionality.
  25  */
  26 published interface XStorage
  27 {
  28     // INTERFACES
  29     /** allows to get list of child elements and to check if an element with a
  30         specified name exists in a storage.
  31
  32         <p>
  33         It is also possible to use this interface to get read access to
  34         a child element by
  35         com::sun::star::container::XNameAccess::getByName()
  36         call. But the recommended way is to use XStorage
  37         interface for this purpose.
  38         </p>
  39      */
  40     interface ::com::sun::star::container::XNameAccess;
  41
  42     /** allows to control and track lifetime of the storage.
  43
  44         <p>
  45         In case a storage is disposed any call to its methods should result
  46         in com::sun::star::lang::DisposedException.
  47         </p>
  48      */
  49     interface ::com::sun::star::lang::XComponent;
  50
  51
  52     // METHODS
  53     /** allows to copy current storage to another one
  54
  55         <p>
  56         The destination storage contents are overwritten.
  57         After the successful copying the target storage is automatically
  58         committed if it implements transacted access.
  59         </p>
  60
  61         @param xDest
  62             a destination storage this storage must be copied to.
  63
  64         @throws ::com::sun::star::embed::InvalidStorageException
  65             this storage is in invalid state for any reason
  66
  67         @throws ::com::sun::star::lang::IllegalArgumentException
  68             an illegal argument is provided
  69
  70         @throws ::com::sun::star::io::IOException
  71             in case of io errors during copying
  72
  73         @throws ::com::sun::star::embed::StorageWrappedTargetException
  74             wraps other exception acquired during copying
  75      */
  76     void copyToStorage( [in] XStorage xDest )
  77         raises( ::com::sun::star::embed::InvalidStorageException,
  78                 ::com::sun::star::lang::IllegalArgumentException,
  79                 ::com::sun::star::io::IOException,
  80                 ::com::sun::star::embed::StorageWrappedTargetException );
  81
  82     /** allows to get access to a child stream of the storage.
  83
  84         <p>
  85         In case the stream is open in readonly mode the
  86         com::sun::star::io::XStream::getOutputStream()
  87         method will return an empty reference.
  88         </p>
  89
  90         @param sStreamName
  91             the name of the substream that should be open
  92
  93         @param nOpenMode
  94             a mode the stream should be open in,
  95             can be a combination of ElementModes values
  96
  97         @throws ::com::sun::star::embed::InvalidStorageException
  98             this storage is in invalid state for any reason
  99
 100         @throws ::com::sun::star::lang::IllegalArgumentException
 101             one of provided arguments is illegal
 102
 103         @throws ::com::sun::star::packages::WrongPasswordException
 104             the provided password is wrong
 105
 106         @throws ::com::sun::star::io::IOException
 107             in case of io errors during stream opening
 108
 109         @throws ::com::sun::star::embed::StorageWrappedTargetException
 110             wraps other exceptions
 111      */
 112     ::com::sun::star::io::XStream  openStreamElement(
 113             [in] string sStreamName,
 114             [in] long nOpenMode )
 115         raises( ::com::sun::star::embed::InvalidStorageException,
 116                 ::com::sun::star::lang::IllegalArgumentException,
 117                 ::com::sun::star::packages::WrongPasswordException,
 118                 ::com::sun::star::io::IOException,
 119                 ::com::sun::star::embed::StorageWrappedTargetException );
 120
 121     /** allows to get access to a child encrypted stream with password.
 122
 123         <p>
 124         If storage does not allow any encryption this method will always throw
 125         com::sun::star::packages::NoEncryptionException.
 126         </p>
 127
 128         <p>
 129         In case the stream is open in readonly mode the
 130         com::sun::star::io::XStream::getOutputStream()
 131         method will return an empty reference.
 132         </p>
 133
 134         @param sStreamName
 135             the name of the substream that should be open
 136
 137         @param nOpenMode
 138             a mode the stream should be open in,
 139             can be a combination of ElementModes values
 140
 141         @param sPassword
 142             this parameter allows to specify a reading password for the
 143             stream, the password must be a correct one, otherwise an
 144             exception will be thrown
 145
 146         @throws ::com::sun::star::embed::InvalidStorageException
 147             this storage is in invalid state for any reason
 148
 149         @throws ::com::sun::star::lang::IllegalArgumentException
 150             one of provided arguments is illegal
 151
 152         @throws ::com::sun::star::packages::NoEncryptionException
 153             the stream is not encrypted
 154
 155         @throws ::com::sun::star::packages::WrongPasswordException
 156             the provided password is wrong
 157
 158         @throws ::com::sun::star::io::IOException
 159             in case of io errors during stream opening
 160
 161         @throws ::com::sun::star::embed::StorageWrappedTargetException
 162             wraps other exceptions
 163      */
 164     ::com::sun::star::io::XStream  openEncryptedStreamElement(
 165             [in] string sStreamName,
 166             [in] long nOpenMode,
 167             [in] string sPassword )
 168         raises( ::com::sun::star::embed::InvalidStorageException,
 169                 ::com::sun::star::lang::IllegalArgumentException,
 170                 ::com::sun::star::packages::NoEncryptionException,
 171                 ::com::sun::star::packages::WrongPasswordException,
 172                 ::com::sun::star::io::IOException,
 173                 ::com::sun::star::embed::StorageWrappedTargetException );
 174
 175     /** allows to get access to a child storage.
 176
 177         <p>
 178         The opened substorage must support specified in "nOpenMode" access
 179         modes. It can support "read" mode in addition. But any child element
 180         can support one of those modes only in case this mode is supported by
 181         parent storage.
 182         </p>
 183
 184         @param sStorName
 185             the name of the storage that should be open
 186
 187         @param nOpenMode
 188             a mode the storage should be open in
 189
 190         @throws ::com::sun::star::embed::InvalidStorageException
 191             this storage is in invalid state for any reason
 192
 193         @throws ::com::sun::star::lang::IllegalArgumentException
 194             one of provided arguments is illegal
 195
 196         @throws ::com::sun::star::io::IOException
 197             in case of io errors during stream opening
 198
 199         @throws ::com::sun::star::embed::StorageWrappedTargetException
 200             wraps other exceptions
 201
 202      */
 203     XStorage openStorageElement( [in] string sStorName,
 204                                  [in] long nOpenMode )
 205         raises( ::com::sun::star::embed::InvalidStorageException,
 206                 ::com::sun::star::lang::IllegalArgumentException,
 207                 ::com::sun::star::io::IOException,
 208                 ::com::sun::star::embed::StorageWrappedTargetException );
 209
 210     /** allows to get readonly copy of a child stream of the storage.
 211
 212         <p>
 213         The stream is open in readonly mode so the
 214         com::sun::star::io::XStream::getOutputStream()
 215         method will return an empty reference.
 216         </p>
 217
 218         @param sStreamName
 219             the name of the substream that should be copied
 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::WrongPasswordException
 228             the provided password is wrong
 229
 230         @throws ::com::sun::star::io::IOException
 231             in case of io errors during stream opening
 232
 233         @throws ::com::sun::star::embed::StorageWrappedTargetException
 234             wraps other exceptions
 235      */
 236     ::com::sun::star::io::XStream cloneStreamElement( [in] string sStreamName )
 237         raises( ::com::sun::star::embed::InvalidStorageException,
 238                 ::com::sun::star::lang::IllegalArgumentException,
 239                 ::com::sun::star::packages::WrongPasswordException,
 240                 ::com::sun::star::io::IOException,
 241                 ::com::sun::star::embed::StorageWrappedTargetException );
 242
 243     /** allows to get readonly copy of a child encrypted stream with password.
 244
 245         <p>
 246         If storage does not allow any encryption this method will always throw
 247         com::sun::star::packages::NoEncryptionException.
 248         </p>
 249
 250         <p>
 251         The stream is open in readonly mode so the
 252         com::sun::star::io::XStream::getOutputStream()
 253         method will return an empty reference.
 254         </p>
 255
 256         <p>
 257         This method allows to specify reading password for the child stream
 258         explicitly.
 259         </p>
 260
 261         @param sStreamName
 262             the name of the substream that should be copied
 263
 264         @param sPassword
 265             this parameter allows to specify a reading password for the
 266             stream, the password must be a correct one, otherwise an
 267             exception will be thrown
 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::packages::NoEncryptionException
 276             the stream is not encrypted
 277
 278         @throws ::com::sun::star::packages::WrongPasswordException
 279             the provided password is wrong
 280
 281         @throws ::com::sun::star::io::IOException
 282             in case of io errors during stream opening
 283
 284         @throws ::com::sun::star::embed::StorageWrappedTargetException
 285             wraps other exceptions
 286      */
 287     ::com::sun::star::io::XStream cloneEncryptedStreamElement(
 288             [in] string sStreamName,
 289             [in] string sPassword )
 290         raises( ::com::sun::star::embed::InvalidStorageException,
 291                 ::com::sun::star::lang::IllegalArgumentException,
 292                 ::com::sun::star::packages::NoEncryptionException,
 293                 ::com::sun::star::packages::WrongPasswordException,
 294                 ::com::sun::star::io::IOException,
 295                 ::com::sun::star::embed::StorageWrappedTargetException );
 296
 297     /** allows to get copy of this storage at the state of its last commit.
 298
 299         <p>
 300         This method makes sense only for services implementations that allow
 301         transaction in the storage.
 302         </p>
 303
 304         @param xTargetStorage
 305             the target storage that will be filled in with copy.
 306
 307         @throws ::com::sun::star::embed::InvalidStorageException
 308             this storage is in invalid state for any reason
 309
 310         @throws ::com::sun::star::lang::IllegalArgumentException
 311             one of provided arguments is illegal
 312
 313         @throws ::com::sun::star::io::IOException
 314             in case of io errors during copying
 315
 316         @throws ::com::sun::star::embed::StorageWrappedTargetException
 317             wraps other exceptions
 318
 319      */
 320     void copyLastCommitTo( [in] XStorage xTargetStorage )
 321         raises( ::com::sun::star::embed::InvalidStorageException,
 322                 ::com::sun::star::lang::IllegalArgumentException,
 323                 ::com::sun::star::io::IOException,
 324                 ::com::sun::star::embed::StorageWrappedTargetException );
 325
 326     /** allows to get copy of a child storage at the state of its last commit.
 327
 328         <p>
 329         This method makes sense only for services implementations that allow
 330         transaction in the storage.
 331         </p>
 332
 333         @param sStorName
 334             the name of the storage that should be copied
 335
 336         @param xTargetStorage
 337             the target storage that will be filled in with copy
 338
 339         @throws ::com::sun::star::embed::InvalidStorageException
 340             this storage is in invalid state for any reason
 341
 342         @throws ::com::sun::star::lang::IllegalArgumentException
 343             one of provided arguments is illegal
 344
 345         @throws ::com::sun::star::io::IOException
 346             in case of io errors during copying
 347
 348         @throws ::com::sun::star::embed::StorageWrappedTargetException
 349             wraps other exceptions
 350
 351      */
 352     void copyStorageElementLastCommitTo(
 353             [in] string sStorName,
 354             [in] XStorage xTargetStorage )
 355         raises( ::com::sun::star::embed::InvalidStorageException,
 356                 ::com::sun::star::lang::IllegalArgumentException,
 357                 ::com::sun::star::io::IOException,
 358                 ::com::sun::star::embed::StorageWrappedTargetException );
 359
 360     /** allows to check if an element is a child stream with specified name.
 361
 362         <p>
 363         In case there is no child element with such name an exception will be
 364         thrown.
 365         </p>
 366
 367         @param sElementName
 368             the name of the element to check
 369
 370         @returns
 371             `TRUE` in case the element is a stream
 372             `FALSE` - the element is a storage
 373
 374         @throws ::com::sun::star::container::NoSuchElementException
 375             there is no element with such name
 376
 377         @throws ::com::sun::star::lang::IllegalArgumentException
 378             an illegal argument is provided
 379
 380         @throws ::com::sun::star::embed::InvalidStorageException
 381             this storage is in invalid state for any reason
 382
 383      */
 384     boolean isStreamElement( [in] string sElementName )
 385         raises( ::com::sun::star::container::NoSuchElementException,
 386                 ::com::sun::star::lang::IllegalArgumentException,
 387                 ::com::sun::star::embed::InvalidStorageException );
 388
 389
 390     /** allows to check if an element is a child storage with specified name.
 391
 392         <p>
 393         In case there is no child element with such name an exception will be
 394         thrown.
 395         </p>
 396
 397         @param sElementName
 398             the name of the element to check
 399
 400         @returns
 401             `TRUE` in case the element is a storage
 402             `FALSE` - the element is a stream
 403
 404         @throws ::com::sun::star::container::NoSuchElementException
 405             there is no element with such name
 406
 407         @throws ::com::sun::star::lang::IllegalArgumentException
 408             an illegal argument is provided
 409
 410         @throws ::com::sun::star::embed::InvalidStorageException
 411             this storage is in invalid state for any reason
 412
 413      */
 414     boolean isStorageElement( [in] string sElementName )
 415         raises( ::com::sun::star::container::NoSuchElementException,
 416                 ::com::sun::star::lang::IllegalArgumentException,
 417                 ::com::sun::star::embed::InvalidStorageException );
 418
 419     /** removes an element from a storage.
 420
 421         @param sElementName
 422             the name of the element to remove
 423
 424         @throws ::com::sun::star::embed::InvalidStorageException
 425             this storage is in invalid state for any reason
 426
 427         @throws ::com::sun::star::lang::IllegalArgumentException
 428             an illegal argument is provided
 429
 430         @throws ::com::sun::star::container::NoSuchElementException
 431             there is no element with such name
 432
 433         @throws ::com::sun::star::io::IOException
 434             in case of io errors during removing
 435
 436         @throws ::com::sun::star::embed::StorageWrappedTargetException
 437             wraps other exceptions
 438
 439      */
 440     void removeElement( [in] string sElementName )
 441         raises( ::com::sun::star::embed::InvalidStorageException,
 442                 ::com::sun::star::lang::IllegalArgumentException,
 443                 ::com::sun::star::container::NoSuchElementException,
 444                 ::com::sun::star::io::IOException,
 445                 ::com::sun::star::embed::StorageWrappedTargetException );
 446
 447     /** renames an element in a storage.
 448
 449         @param sElementName
 450             the old name of the element to rename
 451
 452         @param sNewName
 453             the new name of the element to rename
 454
 455         @throws ::com::sun::star::embed::InvalidStorageException
 456             this storage is in invalid state for any reason
 457
 458         @throws ::com::sun::star::lang::IllegalArgumentException
 459             an illegal argument is provided
 460
 461         @throws ::com::sun::star::container::NoSuchElementException
 462             there is no element with old name in this storage
 463
 464         @throws ::com::sun::star::container::ElementExistException
 465             an element with new name already exists in this storage
 466
 467         @throws ::com::sun::star::io::IOException
 468             in case of io errors during renaming
 469
 470         @throws ::com::sun::star::embed::StorageWrappedTargetException
 471             wraps other exceptions
 472
 473      */
 474     void renameElement( [in] string sElementName, [in] string sNewName )
 475         raises( ::com::sun::star::embed::InvalidStorageException,
 476                 ::com::sun::star::lang::IllegalArgumentException,
 477                 ::com::sun::star::container::NoSuchElementException,
 478                 ::com::sun::star::container::ElementExistException,
 479                 ::com::sun::star::io::IOException,
 480                 ::com::sun::star::embed::StorageWrappedTargetException );
 481
 482     /** allows to copy an entry from one storage to another.
 483
 484         <p>
 485         If target element supports transacted mode it must be committed by this
 486         method after successful copying.
 487         </p>
 488
 489         @param sElementName
 490             the name of the element in this storage
 491
 492         @param xDest
 493             a destination storage
 494
 495         @param sNewName
 496             the name of the result element in destination storage
 497
 498         @throws ::com::sun::star::embed::InvalidStorageException
 499             this storage is in invalid state for any reason
 500
 501         @throws ::com::sun::star::container::NoSuchElementException
 502             there is no specified source element in this storage
 503
 504         @throws ::com::sun::star::container::ElementExistException
 505             an element with specified destination name already exists in destination storage
 506
 507         @throws ::com::sun::star::io::IOException
 508             in case of io errors during copying
 509
 510         @throws ::com::sun::star::embed::StorageWrappedTargetException
 511             wraps other exceptions
 512
 513      */
 514     void copyElementTo(
 515             [in] string sElementName,
 516             [in] XStorage xDest,
 517             [in] string sNewName )
 518         raises( ::com::sun::star::embed::InvalidStorageException,
 519                 ::com::sun::star::lang::IllegalArgumentException,
 520                 ::com::sun::star::container::NoSuchElementException,
 521                 ::com::sun::star::container::ElementExistException,
 522                 ::com::sun::star::io::IOException,
 523                 ::com::sun::star::embed::StorageWrappedTargetException );
 524
 525     /** allows to move an entry from one storage to another.
 526
 527         <p>
 528         If target element supports transacted mode it must be committed by this
 529         method after successful moving.
 530         </p>
 531
 532         @param sElementName
 533             the name of the element in this storage
 534
 535         @param xDest
 536             a destination storage
 537
 538         @param sNewName
 539             the name of the result element in destination storage
 540
 541         @throws ::com::sun::star::embed::InvalidStorageException
 542             this storage is in invalid state for any reason
 543
 544         @throws ::com::sun::star::container::NoSuchElementException
 545             there is no specified source element in this storage
 546
 547         @throws ::com::sun::star::container::ElementExistException
 548             an element with specified destination name already exists in destination storage
 549
 550         @throws ::com::sun::star::io::IOException
 551             in case of io errors during moving
 552
 553         @throws ::com::sun::star::embed::StorageWrappedTargetException
 554             wraps other exceptions
 555
 556      */
 557     void moveElementTo(
 558             [in] string sElementName,
 559             [in] XStorage xDest,
 560             [in] string sNewName )
 561         raises( ::com::sun::star::embed::InvalidStorageException,
 562                 ::com::sun::star::lang::IllegalArgumentException,
 563                 ::com::sun::star::container::NoSuchElementException,
 564                 ::com::sun::star::container::ElementExistException,
 565                 ::com::sun::star::io::IOException,
 566                 ::com::sun::star::embed::StorageWrappedTargetException );
 567
 568 };
 569
 570
 571 }; }; }; };
 572
 573 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */