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