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