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