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 */
67published 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
240