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