offapi/com/sun/star/embed/StorageStream.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: StorageStream.idl,v $
  10  * $Revision: 1.6 $
  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
  31 #ifndef __com_sun_star_embed_StorageStream_idl__
  32 #define __com_sun_star_embed_StorageStream_idl__
  33
  34 #ifndef __com_sun_star_embed_XEncryptionProtectedSource_idl__
  35 #include <com/sun/star/embed/XEncryptionProtectedSource.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_lang_XComponent_idl__
  39 #include <com/sun/star/lang/XComponent.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_beans_XPropertySet_idl__
  43 #include <com/sun/star/beans/XPropertySet.idl>
  44 #endif
  45
  46 #ifndef __com_sun_star_io_XStream_idl__
  47 #include <com/sun/star/io/XStream.idl>
  48 #endif
  49
  50 #ifndef __com_sun_star_io_XSeekable_idl__
  51 #include <com/sun/star/io/XSeekable.idl>
  52 #endif
  53
  54
  55
  56 //============================================================================
  57
  58  module com {  module sun {  module star {  module embed {
  59
  60 //============================================================================
  61 /**  This is a service that represents a stream that can be provided by
  62     <type>XStorage</type>::openStreamElement() call implemented by
  63     <type>Storage</type> service.
  64
  65     <p>
  66     In case a stream is open with readwrite access only one instance
  67     of the stream can exist.
  68     </p>
  69  */
  70 service StorageStream
  71 {
  72     // -----------------------------------------------------------------------
  73     /** allows to get access to <type scope="com::sun::star::io">XInputStream</type>
  74         and <type scope="com::sun::star::io">XOutputStream</type>
  75         implementations.
  76
  77         <p>
  78         In case the storage stream is open readonly the returned reference
  79         to <type scope="com::sun::star::io">XOutputStream</type> will be
  80         empty.
  81         </p>
  82     */
  83     interface ::com::sun::star::io::XStream;
  84
  85     // -----------------------------------------------------------------------
  86     /** allows to control object lifetime.
  87
  88         <p>
  89         A storage stream is created by a storage and has a restrictions
  90         depending on the mode the stream is opened in.
  91         </p>
  92
  93         <p>
  94         In case a stream is opened with read-write access only one instance of
  95         the stream can exist. It means that the stream can not be reopened
  96         even for readonly access until the readwrite instance is disposed.
  97         From the other side it is possible to open multiple streams for
  98         readonly access. But because of the rule mentioned above it will not
  99         be possible to open the stream for read-write access until all the
 100         readonly instances are disposed.
 101         </p>
 102
 103         <p>
 104         The stream must be disposed by
 105         <member scope="com::sun::star::lang">XComponent::dispose()</member>
 106         call or by explicit closing of input and output ( if provided )
 107         streams implementations with
 108         <member scope="com::sun::star::io">XInputStream::closeInput()</member>
 109         and
 110         <member scope="com::sun::star::io">XOutputStream::closeOutput()</member>
 111         calls.
 112         </p>
 113
 114         <p>
 115         When a stream is disposed all the changes that were done for it are
 116         automatically flashed, so that they becomes visible from parent
 117         storage. It is also possible to flash the stream explicitly.
 118         </p>
 119
 120         <p>
 121         In case parent storage is disposed the stream is disposed
 122         automatically.
 123         </p>
 124
 125         <p>
 126         In case a stream is disposed any call to it's methods should result in
 127         <type scope="com::sun::star::lang">DisposedException</type>.
 128         </p>
 129      */
 130     interface ::com::sun::star::lang::XComponent;
 131
 132     // -----------------------------------------------------------------------
 133     /** allows to get access to stream properties.
 134      */
 135     interface ::com::sun::star::beans::XPropertySet;
 136
 137     // -----------------------------------------------------------------------
 138     /** allows to seek to a specified position within the stream.
 139
 140         <p>
 141         This interface must be supported in case either seekable readonly
 142         or read-write access is requested.
 143         </p>
 144      */
 145     [optional]
 146     interface ::com::sun::star::io::XSeekable;
 147
 148     // -----------------------------------------------------------------------
 149     /** allows to set password to the stream.
 150
 151         <p>
 152         This interface must be supported by a stream with readwrite access
 153         to allow to set a password that should be used next time the
 154         stream is stored.
 155         </p>
 156
 157         <p>
 158         If the password is set or changed by this interface and the
 159         stream is closed the new password should be used to get access to the
 160         stream next time.
 161         </p>
 162      */
 163     [optional]
 164     interface ::com::sun::star::embed::XEncryptionProtectedSource;
 165
 166     // -----------------------------------------------------------------------
 167     /** allows to get and set media type of the stream.
 168      */
 169     [property] string MediaType;
 170
 171     // -----------------------------------------------------------------------
 172     /** specifies if the stream should be compressed next time it is stored.
 173      */
 174     [property] boolean IsCompressed;
 175
 176     // -----------------------------------------------------------------------
 177     /** allows to detect if the stream is encrypted.
 178
 179         <p>
 180         The property value <TRUE/> means that the stream is currently encrypted.
 181         <FALSE/> - the stream is not encrypted.
 182         </p>
 183
 184         <p>
 185         If somebody sets a password explicitly by using
 186         <type>XEncryptionProtectedSource</type> interface the value is
 187         automatically set to <TRUE/>. If the interface is used to remove
 188         the encryption - the value is automatically set to <FALSE/>.
 189         </p>
 190
 191      */
 192     [property, readonly] boolean IsEncrypted;
 193
 194     // -----------------------------------------------------------------------
 195     /** specifies whether the stream will become encrypted next time the
 196         common storage password holder is commited.
 197
 198         <p>
 199         The property value <TRUE/> means that the stream will become encrypted
 200         after the closest storage in the parent hierarchy, that has common
 201         storage password, is commited.
 202         <FALSE/> - the stream will not react to commit of such a storage.
 203         </p>
 204
 205         <p>
 206         In case stream is not encrypted and the property is set to <TRUE/>,
 207         the stream will stay nonencrypted until the closest storage
 208         in the parent hierarchy, that has common storage password, is commited.
 209         On the commit the stream will be encrypted with the common storage
 210         password. If there is no such storage in the hierarchy the stream
 211         will not be encrypted at all.
 212         Thus this property must be set very carefully.
 213         </p>
 214
 215         <p>
 216         If somebody sets a password explicitly by using
 217         <type>XEncryptionProtectedSource</type> interface the value is
 218         automatically set to <FALSE/> and the stream becomes encrypted
 219         with specified password immediatelly.
 220         </p>
 221
 222         <p>
 223         In case stream is encrypted one and the value is set to <TRUE/>
 224         the stream becomes nonencrypted until the common storage password
 225         holder is commited. The data about previously set password ( if any )
 226         will be removed and the stream can be accessed as nonencrypted stream.
 227         </p>
 228      */
 229     [property] boolean UseCommonStoragePasswordEncryption;
 230
 231     // -----------------------------------------------------------------------
 232     /** allows to detect size of the stream in bytes.
 233      */
 234     [property, readonly] long Size;
 235 };
 236
 237 //============================================================================
 238
 239 }; }; }; };
 240
 241 #endif
 242