include/unotools/mediadescriptor.hxx

   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 INCLUDED_UNOTOOLS_MEDIADESCRIPTOR_HXX
  21 #define INCLUDED_UNOTOOLS_MEDIADESCRIPTOR_HXX
  22
  23 #include <sal/config.h>
  24
  25 #include <vector>
  26
  27 #include <comphelper/docpasswordrequest.hxx>
  28 #include <comphelper/sequenceashashmap.hxx>
  29 #include <rtl/ustring.hxx>
  30 #include <unotools/unotoolsdllapi.h>
  31
  32 namespace com::sun::star::io {
  33     class XInputStream;
  34 }
  35 namespace comphelper { class IDocPasswordVerifier; }
  36
  37 namespace utl {
  38
  39 /** @short  can be used to work with a css::document::MediaDescriptor
  40             struct.
  41
  42     @descr  It wraps an unordered_map around the Sequence< css::beans::PropertyValue >, which
  43             represent the MediaDescriptor item.
  44             Further this helper defines often used functions (as e.g. open of the required streams,
  45             consistent checks etcpp.) and it defines all usable property names.
  46
  47     @attention  This class isn't threadsafe and must be guarded from outside!
  48  */
  49 class UNOTOOLS_DLLPUBLIC MediaDescriptor : public comphelper::SequenceAsHashMap
  50 {
  51     public:
  52
  53         /** @short  these methods can be used to get the different property names
  54                     as static const OUString values.
  55
  56             @descr  Because definition and declaration of static const class members
  57                     does not work as expected under windows (under unix it works as well)
  58                     these way must be used :-(
  59           */
  60         static constexpr OUString PROP_ABORTED = u"Aborted"_ustr;
  61         static constexpr OUString PROP_ASTEMPLATE = u"AsTemplate"_ustr;
  62         static constexpr OUString PROP_COMPONENTDATA = u"ComponentData"_ustr;
  63         static constexpr OUString PROP_DOCUMENTSERVICE = u"DocumentService"_ustr;
  64         static constexpr OUString PROP_ENCRYPTIONDATA = u"EncryptionData"_ustr;
  65         static constexpr OUString PROP_FILENAME = u"FileName"_ustr;
  66         static constexpr OUString PROP_FILTERNAME = u"FilterName"_ustr;
  67         static constexpr OUString PROP_FILTERPROVIDER = u"FilterProvider"_ustr;
  68         static constexpr OUString PROP_FILTEROPTIONS = u"FilterOptions"_ustr;
  69         static constexpr OUString PROP_FRAME = u"Frame"_ustr;
  70         static constexpr OUString PROP_FRAMENAME = u"FrameName"_ustr;
  71         static constexpr OUString PROP_HIDDEN = u"Hidden"_ustr;
  72         static constexpr OUString PROP_INPUTSTREAM = u"InputStream"_ustr;
  73         static constexpr OUString PROP_INTERACTIONHANDLER = u"InteractionHandler"_ustr;
  74         static constexpr OUString PROP_AUTHENTICATIONHANDLER = u"AuthenticationHandler"_ustr;
  75         static constexpr OUString PROP_JUMPMARK = u"JumpMark"_ustr;
  76         static constexpr OUString PROP_MACROEXECUTIONMODE = u"MacroExecutionMode"_ustr;
  77         static constexpr OUString PROP_MEDIATYPE = u"MediaType"_ustr;
  78         static constexpr OUString PROP_MINIMIZED = u"Minimized"_ustr;
  79         static constexpr OUString PROP_NOAUTOSAVE = u"NoAutoSave"_ustr;
  80         static constexpr OUString PROP_OPENNEWVIEW = u"OpenNewView"_ustr;
  81         static constexpr OUString PROP_OUTPUTSTREAM = u"OutputStream"_ustr;
  82         static constexpr OUString PROP_PASSWORD = u"Password"_ustr;
  83         static constexpr OUString PROP_POSTDATA = u"PostData"_ustr;
  84         static constexpr OUString PROP_PREVIEW = u"Preview"_ustr;
  85         static constexpr OUString PROP_READONLY = u"ReadOnly"_ustr;
  86         static constexpr OUString PROP_REFERRER = u"Referer"_ustr;
  87         static constexpr OUString PROP_REPLACEABLE = u"Replaceable"_ustr;
  88         static constexpr OUString PROP_SALVAGEDFILE = u"SalvagedFile"_ustr;
  89         static constexpr OUString PROP_SILENT = u"Silent"_ustr;
  90         static constexpr OUString PROP_STATUSINDICATOR = u"StatusIndicator"_ustr;
  91         static constexpr OUString PROP_STREAM = u"Stream"_ustr;
  92         static constexpr OUString PROP_STREAMFOROUTPUT = u"StreamForOutput"_ustr;
  93         static constexpr OUString PROP_TEMPLATENAME = u"TemplateName"_ustr;
  94         static constexpr OUString PROP_TITLE = u"Title"_ustr;
  95         static constexpr OUString PROP_TYPENAME = u"TypeName"_ustr;
  96         static constexpr OUString PROP_UCBCONTENT = u"UCBContent"_ustr;
  97         static constexpr OUString PROP_UPDATEDOCMODE = u"UpdateDocMode"_ustr;
  98         static constexpr OUString PROP_URL = u"URL"_ustr;
  99         static constexpr OUString PROP_VERSION = u"Version"_ustr;
 100         static constexpr OUString PROP_DOCUMENTTITLE = u"DocumentTitle"_ustr;
 101         static constexpr OUString PROP_MODEL = u"Model"_ustr;
 102         static constexpr OUString PROP_VIEWONLY = u"ViewOnly"_ustr;
 103         static constexpr OUString PROP_DOCUMENTBASEURL = u"DocumentBaseURL"_ustr;
 104         static constexpr OUString PROP_SUGGESTEDSAVEASNAME = u"SuggestedSaveAsName"_ustr;
 105         static constexpr OUString PROP_AUTOSAVEEVENT = u"AutoSaveEvent"_ustr;
 106
 107     // interface
 108     public:
 109
 110         /** @short  these ctors do nothing - excepting that they forward
 111                     the given parameters to the base class ctors.
 112
 113             @descr  The ctors must be overwritten to resolve conflicts with
 114                     the default ctors of the compiler :-(.
 115          */
 116         MediaDescriptor();
 117         MediaDescriptor(const css::uno::Sequence< css::beans::PropertyValue >& lSource);
 118
 119         /** @short  it checks if the descriptor already has a valid
 120                     InputStream item and creates a new one, if not.
 121
 122             @descr  This method uses the current items of this MediaDescriptor,
 123                     to open the stream (as e.g. URL, ReadOnly, PostData etcpp.).
 124                     It creates a seekable stream and put it into the descriptor.
 125
 126                     A might existing InteractionHandler will be used automatically,
 127                     to solve problems!
 128
 129                     In case of local file the system file locking is used.
 130
 131             @return TRUE, if the stream was already part of the descriptor or could
 132                     be created as new item. FALSE otherwise.
 133          */
 134         bool addInputStream();
 135
 136         /** @short  it checks if the descriptor already has a valid
 137                     InputStream item and creates a new one, if not.
 138
 139             @descr  This method uses the current items of this MediaDescriptor,
 140                     to open the stream (as e.g. URL, ReadOnly, PostData etcpp.).
 141                     It creates a seekable stream and put it into the descriptor.
 142
 143                     A might existing InteractionHandler will be used automatically,
 144                     to solve problems!
 145
 146                     In case of local file the system file locking is used based on
 147                     configuration settings.
 148
 149             @return TRUE, if the stream was already part of the descriptor or could
 150                     be created as new item. FALSE otherwise.
 151          */
 152         bool addInputStreamOwnLock();
 153
 154         /** @short  it checks if the descriptor describes a readonly stream.
 155
 156             @descr  The descriptor itself isn't changed doing so.
 157                     It's only checked if the stream seems to be based
 158                     of a real readonly file.
 159
 160             @Attention
 161                     We don't check the property "ReadOnly" here. Because
 162                     this property can be set from outside and overwrites
 163                     the readonly state of  the stream.
 164                     If e.g. the stream could be opened read/write ...
 165                     but "ReadOnly" property is set to TRUE, this means:
 166                     show a readonly UI on top of this read/write stream.
 167
 168             @return TRUE, if the stream must be interpreted as readonly ...
 169                     FALSE otherwise.
 170          */
 171         bool isStreamReadOnly() const;
 172
 173         /** Returns a value from the sequence contained in the property
 174             'ComponentData' of this media descriptor.
 175
 176             @descr  The property 'ComponentData' should be empty, or should
 177                 contain a value of type sequence<com.sun.star.beans.NamedValue>
 178                 or sequence<com.sun.star.beans.PropertyValue>.
 179
 180             @return  The value with the specified name, if existing in the
 181                 sequence of the 'ComponentData' property, otherwise an empty
 182                 Any.
 183          */
 184         css::uno::Any getComponentDataEntry(
 185             const OUString& rName ) const;
 186
 187         /** Inserts a value into the sequence contained in the property
 188             'ComponentData' of the media descriptor.
 189
 190             @descr  The property 'ComponentData' should be empty, or should
 191                 contain a value of type sequence<com.sun.star.beans.NamedValue>
 192                 or sequence<com.sun.star.beans.PropertyValue>. The passed value
 193                 will be inserted into the sequence, or, if already existing,
 194                 will be overwritten.
 195
 196             @param rName  The name of the value to be inserted into the
 197                 sequence of the 'ComponentData' property.
 198
 199             @param rValue  The value to be inserted into the sequence of the
 200                 'ComponentData' property.
 201          */
 202         void setComponentDataEntry(
 203             const OUString& rName,
 204             const css::uno::Any& rValue );
 205
 206         /** Removes a value from the sequence contained in the property
 207             'ComponentData' of the media descriptor.
 208
 209             @descr  The property 'ComponentData' should be empty, or should
 210                 contain a value of type sequence<com.sun.star.beans.NamedValue>
 211                 or sequence<com.sun.star.beans.PropertyValue>. The value with
 212                 the passed name will be removed from the sequence, if existing.
 213
 214             @param rName  The name of the value to be removed from the sequence
 215                 of the 'ComponentData' property.
 216          */
 217         void clearComponentDataEntry(
 218             const OUString& rName );
 219
 220         /** This helper function tries to find a password for the document
 221             described by this media descriptor.
 222
 223             First, the list of default passwords will be tried if provided. This
 224             is needed by import filters for external file formats that have to
 225             check a predefined password in some cases without asking the user
 226             for a password. Every password is checked using the passed password
 227             verifier.
 228
 229             If not successful, this media descriptor is asked for a password,
 230             that has been set e.g. by an API call to load a document. If
 231             existing, the password is checked using the passed password
 232             verifier.
 233
 234             If still not successful, the interaction handler contained in this
 235             media descriptor is used to request a password from the user. This
 236             will be repeated until the passed password verifier validates the
 237             entered password, or if the user chooses to cancel password input.
 238
 239             If a valid password (that is not contained in the passed list of
 240             default passwords) was found, it will be inserted into the
 241             "Password" property of this descriptor.
 242
 243             @param rVerifier
 244             The password verifier used to check every processed password.
 245
 246             @param eRequestType
 247             The password request type that will be passed to the
 248             DocPasswordRequest object created internally. See
 249             docpasswordrequest.hxx for more details.
 250
 251             @param pDefaultPasswords
 252             If not null, contains default passwords that will be tried before a
 253             password will be requested from the media descriptor or the user.
 254
 255             @return
 256             If not empty, contains the password that has been validated by the
 257             passed password verifier. If empty, no valid password has been
 258             found, or the user has chosen to cancel password input.
 259         */
 260         css::uno::Sequence< css::beans::NamedValue > requestAndVerifyDocPassword(
 261             comphelper::IDocPasswordVerifier& rVerifier,
 262             comphelper::DocPasswordRequestType eRequestType,
 263             const ::std::vector< OUString >* pDefaultPasswords );
 264
 265     // helper
 266     private:
 267
 268         /** @short  tries to open a stream by using the given PostData stream.
 269
 270             @descr  The stream is used directly ...
 271
 272                     The MediaDescriptor itself is changed inside this method.
 273                     Means: the stream is added internal and not returned by a value.
 274
 275             @param  _rxPostData
 276                     the PostData stream.
 277
 278             @return TRUE if the stream could be added successfully.
 279                     Note: If FALSE is returned, the error was already handled inside!
 280
 281             @throw  [css::uno::RuntimeException]
 282                     if the MediaDescriptor seems to be invalid!
 283
 284             @throw  [css::lang::IllegalArgumentException]
 285                     if the given PostData stream is <NULL/>.
 286          */
 287         SAL_DLLPRIVATE bool impl_openStreamWithPostData(
 288             const css::uno::Reference< css::io::XInputStream >& _rxPostData
 289             );
 290
 291         /** @short  tries to open a stream by using the given URL.
 292
 293             @descr  First it tries to open the content in r/w mode (if its
 294                     allowed to do so). Only in case it's not allowed or it failed
 295                     the stream will be tried to open in readonly mode.
 296
 297                     The MediaDescriptor itself is changed inside this method.
 298                     Means: the stream is added internal and not returned by a value.
 299
 300             @param  sURL
 301                     the URL for open.
 302
 303             @param  bLockFile
 304                     specifies whether the file should be locked
 305
 306             @return TRUE if the stream could be added successfully.
 307                     Note: If FALSE is returned, the error was already handled inside!
 308
 309             @throw  [css::uno::RuntimeException]
 310                     if the MediaDescriptor seems to be invalid!
 311          */
 312         SAL_DLLPRIVATE bool impl_openStreamWithURL(
 313             const OUString& sURL,
 314             bool bLockFile
 315             );
 316
 317         /** @short  it checks if the descriptor already has a valid
 318                     InputStream item and creates a new one, if not.
 319
 320             @descr  This method uses the current items of this MediaDescriptor,
 321                     to open the stream (as e.g. URL, ReadOnly, PostData etcpp.).
 322                     It creates a seekable stream and put it into the descriptor.
 323
 324                     A might existing InteractionHandler will be used automatically,
 325                     to solve problems!
 326
 327             @param  bLockFile
 328                     specifies whether the file should be locked
 329
 330             @return TRUE, if the stream was already part of the descriptor or could
 331                     be created as new item. FALSE otherwise.
 332          */
 333         SAL_DLLPRIVATE bool impl_addInputStream( bool bLockFile );
 334 };
 335
 336 }
 337
 338 #endif
 339
 340 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */