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