offapi/com/sun/star/embed/XHierarchicalStorageAccess.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: XHierarchicalStorageAccess.idl,v $
  10  * $Revision: 1.3 $
  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_XHierarchicalStorageAccess_idl__
  31 #define __com_sun_star_embed_XHierarchicalStorageAccess_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_embed_XExtendedStorageStream_idl__
  42 #include <com/sun/star/embed/XExtendedStorageStream.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_IllegalArgumentException_idl__
  50 #include <com/sun/star/lang/IllegalArgumentException.idl>
  51 #endif
  52
  53 #ifndef __com_sun_star_embed_StorageWrappedTargetException_idl__
  54 #include <com/sun/star/embed/StorageWrappedTargetException.idl>
  55 #endif
  56
  57 #ifndef __com_sun_star_embed_InvalidStorageException_idl__
  58 #include <com/sun/star/embed/InvalidStorageException.idl>
  59 #endif
  60
  61 #ifndef __com_sun_star_packages_WrongPasswordException_idl__
  62 #include <com/sun/star/packages/WrongPasswordException.idl>
  63 #endif
  64
  65 #ifndef __com_sun_star_container_XNameAccess_idl__
  66 #include <com/sun/star/container/XNameAccess.idl>
  67 #endif
  68
  69 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  70 #include <com/sun/star/container/NoSuchElementException.idl>
  71 #endif
  72
  73 #ifndef __com_sun_star_container_ElementExistException_idl__
  74 #include <com/sun/star/container/ElementExistException.idl>
  75 #endif
  76
  77 #ifndef __com_sun_star_packages_NoEncryptionException_idl__
  78 #include <com/sun/star/packages/NoEncryptionException.idl>
  79 #endif
  80
  81
  82 //============================================================================
  83
  84  module com {  module sun {  module star {  module embed {
  85
  86 //============================================================================
  87 /** This interface allows hierarchical access to storage tree.
  88
  89     <p>
  90     Currently only streams can be opened using this interface.
  91     </p>
  92
  93     <p>
  94     The hierarchical access can not be mixed with a normal access. Thus when
  95     in a storage a stream with a path "a/b/c" is accessed using hierarchical
  96     access, another stream "a/b/d" can also be opened with hierarchical
  97     access ( if it is still not opened ), but the substorage "a" can not be
  98     opened ( it is locked by hierarchical access ).
  99     </p>
 100  */
 101 interface XHierarchicalStorageAccess
 102 {
 103     // METHODS
 104     //
 105     // -----------------------------------------------------------------------
 106     /** allows to get access to a child stream of the storage, using
 107         hierarchical path.
 108
 109         <p>
 110         In case the stream is open in readonly mode the
 111         <method scope="com::sun::star::io">XStream::getOutputStream</method>
 112         method will return an empty reference.
 113         </p>
 114
 115         @param sStreamPath
 116             the path to the substream that should be open
 117
 118         @param nOpenMode
 119             a mode the stream should be open in,
 120             can be a combination of <type>ElementModes</type> values
 121
 122         @throws ::com::sun::star::embed::InvalidStorageException
 123             this storage is in invalid state for any reason
 124
 125         @throws ::com::sun::star::lang::IllegalArgumentException
 126             one of provided arguments is illegal
 127
 128         @throws ::com::sun::star::packages::WrongPasswordException
 129             the provided password is wrong
 130
 131         @throws ::com::sun::star::io::IOException
 132             in case of io errors during stream opening
 133
 134         @throws ::com::sun::star::embed::StorageWrappedTargetException
 135             wraps other exceptions
 136      */
 137     XExtendedStorageStream  openStreamElementByHierarchicalName(
 138             [in] string sStreamPath,
 139             [in] long nOpenMode )
 140         raises( ::com::sun::star::embed::InvalidStorageException,
 141                 ::com::sun::star::lang::IllegalArgumentException,
 142                 ::com::sun::star::packages::WrongPasswordException,
 143                 ::com::sun::star::io::IOException,
 144                 ::com::sun::star::embed::StorageWrappedTargetException );
 145
 146     // -----------------------------------------------------------------------
 147     /** allows to get access to a child encrypted stream with password using
 148         hierarchical path.
 149
 150         <p>
 151         If storage does not allow any encryption this method will always throw
 152         <type scope="com::sun::star::packages">NoEncryptionException</type>.
 153         </p>
 154
 155         <p>
 156         In case the stream is open in readonly mode the
 157         <method scope="com::sun::star::io">XStream::getOutputStream</method>
 158         method will return an empty reference.
 159         </p>
 160
 161         @param sStreamPath
 162             the path to the substream that should be open
 163
 164         @param nOpenMode
 165             a mode the stream should be open in,
 166             can be a combination of <type>ElementModes</type> values
 167
 168         @param sPassword
 169             this parameter allowes to specify a reading password for the
 170             stream, the password must be a correct one, otherwise an
 171             exception will be thrown
 172
 173         @throws ::com::sun::star::embed::InvalidStorageException
 174             this storage is in invalid state for any reason
 175
 176         @throws ::com::sun::star::lang::IllegalArgumentException
 177             one of provided arguments is illegal
 178
 179         @throws ::com::sun::star::packages::NoEncryptionException
 180             the stream is not encrypted
 181
 182         @throws ::com::sun::star::packages::WrongPasswordException
 183             the provided password is wrong
 184
 185         @throws ::com::sun::star::io::IOException
 186             in case of io errors during stream opening
 187
 188         @throws ::com::sun::star::embed::StorageWrappedTargetException
 189             wraps other exceptions
 190      */
 191     XExtendedStorageStream  openEncryptedStreamElementByHierarchicalName(
 192             [in] string sStreamName,
 193             [in] long nOpenMode,
 194             [in] string sPassword )
 195         raises( ::com::sun::star::embed::InvalidStorageException,
 196                 ::com::sun::star::lang::IllegalArgumentException,
 197                 ::com::sun::star::packages::NoEncryptionException,
 198                 ::com::sun::star::packages::WrongPasswordException,
 199                 ::com::sun::star::io::IOException,
 200                 ::com::sun::star::embed::StorageWrappedTargetException );
 201
 202     // -----------------------------------------------------------------------
 203     /** removes a stream specified by hierarchical name from a storage.
 204
 205         @param sElementPath
 206             the path to the element to remove
 207
 208         @throws ::com::sun::star::embed::InvalidStorageException
 209             this storage is in invalid state for eny reason
 210
 211         @throws ::com::sun::star::lang::IllegalArgumentException
 212             an illegal argument is provided
 213
 214         @throws ::com::sun::star::container::NoSuchElementException
 215             there is no element with such name
 216
 217         @throws ::com::sun::star::io::IOException
 218             in case of io errors during removing
 219
 220         @throws ::com::sun::star::embed::StorageWrappedTargetException
 221             wraps other exceptions
 222
 223      */
 224     void removeStreamElementByHierarchicalName( [in] string sElementPath )
 225         raises( ::com::sun::star::embed::InvalidStorageException,
 226                 ::com::sun::star::lang::IllegalArgumentException,
 227                 ::com::sun::star::container::NoSuchElementException,
 228                 ::com::sun::star::io::IOException,
 229                 ::com::sun::star::embed::StorageWrappedTargetException );
 230
 231 };
 232
 233 //============================================================================
 234
 235 }; }; }; };
 236
 237 #endif
 238