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