offapi/com/sun/star/embed/StorageStream.idl

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