include/comphelper/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 _COMPHELPER_MEDIADESCRIPTOR_HXX_
  21 #define _COMPHELPER_MEDIADESCRIPTOR_HXX_
  22
  23 #include <comphelper/sequenceashashmap.hxx>
  24 #include <rtl/ustring.hxx>
  25 #include "comphelper/comphelperdllapi.h"
  26
  27 namespace com { namespace sun { namespace star { namespace io {
  28     class XInputStream;
  29 } } } }
  30
  31 namespace comphelper{
  32
  33 /** @short  can be used to work with a <type scope="::com::sun::star::document">MediaDescriptor</type>
  34             struct.
  35
  36     @descr  It wraps a ::boost::unordered_map around the Sequence< css::beans::PropertyValue >, which
  37             represent the MediaDescriptor item.
  38             Further this helper defines often used functions (as e.g. open of the required streams,
  39             consistent checks etcpp.) and it defines all useable property names.
  40
  41     @attention  This class isnt threadsafe and must be guarded from outside!
  42  */
  43 class COMPHELPER_DLLPUBLIC MediaDescriptor : public SequenceAsHashMap
  44 {
  45     public:
  46
  47         //---------------------------------------
  48         /** @short  these methods can be used to get the different property names
  49                     as static const OUString values.
  50
  51             @descr  Because definition and declaration of static const class members
  52                     does not work as expected under windows (under unix it works as well)
  53                     these way must be used :-(
  54           */
  55         static const OUString& PROP_ABORTED();
  56         static const OUString& PROP_ASTEMPLATE();
  57         static const OUString& PROP_COMPONENTDATA();
  58         static const OUString& PROP_DOCUMENTSERVICE();
  59         static const OUString& PROP_ENCRYPTIONDATA();
  60         static const OUString& PROP_FILENAME();
  61         static const OUString& PROP_FILTERNAME();
  62         static const OUString& PROP_FILTERPROVIDER();
  63         static const OUString& PROP_FILTEROPTIONS();
  64         static const OUString& PROP_FRAME();
  65         static const OUString& PROP_FRAMENAME();
  66         static const OUString& PROP_HIDDEN();
  67         static const OUString& PROP_INPUTSTREAM();
  68         static const OUString& PROP_INTERACTIONHANDLER();
  69         static const OUString& PROP_JUMPMARK();
  70         static const OUString& PROP_MACROEXECUTIONMODE();
  71         static const OUString& PROP_MEDIATYPE();
  72         static const OUString& PROP_MINIMIZED();
  73         static const OUString& PROP_NOAUTOSAVE();
  74         static const OUString& PROP_OPENNEWVIEW();
  75         static const OUString& PROP_OUTPUTSTREAM();
  76         static const OUString& PROP_PASSWORD();
  77         static const OUString& PROP_POSTDATA();
  78         static const OUString& PROP_PREVIEW();
  79         static const OUString& PROP_READONLY();
  80         static const OUString& PROP_REFERRER();
  81         static const OUString& PROP_SALVAGEDFILE();
  82         static const OUString& PROP_STATUSINDICATOR();
  83         static const OUString& PROP_STREAM();
  84         static const OUString& PROP_STREAMFOROUTPUT();
  85         static const OUString& PROP_TEMPLATENAME();
  86         static const OUString& PROP_TITLE();
  87         static const OUString& PROP_TYPENAME();
  88         static const OUString& PROP_UCBCONTENT();
  89         static const OUString& PROP_UPDATEDOCMODE();
  90         static const OUString& PROP_URL();
  91         static const OUString& PROP_VERSION();
  92         static const OUString& PROP_DOCUMENTTITLE();
  93         static const OUString& PROP_MODEL();
  94         static const OUString& PROP_VIEWONLY();
  95         static const OUString& PROP_DOCUMENTBASEURL();
  96
  97         static const OUString& PROP_DEEPDETECTION();
  98
  99     //-------------------------------------------
 100     // interface
 101     public:
 102         //---------------------------------------
 103         /** @short  these ctors do nothing - excepting that they forward
 104                     the given parameters to the base class ctors.
 105
 106             @descr  The ctros must be overwritten to resolve conflicts with
 107                     the default ctors of the compiler :-(.
 108          */
 109         MediaDescriptor();
 110         MediaDescriptor(const ::com::sun::star::uno::Sequence< ::com::sun::star::beans::PropertyValue >& lSource);
 111
 112         //---------------------------------------
 113         /** @short  it checks if the descriptor already has a valid
 114                     InputStream item and creates a new one, if not.
 115
 116             @descr  This method uses the current items of this MediaDescriptor,
 117                     to open the stream (as e.g. URL, ReadOnly, PostData etcpp.).
 118                     It creates a seekable stream and put it into the descriptor.
 119
 120                     A might existing InteractionHandler will be used automaticly,
 121                     to solve problems!
 122
 123                     In case of local file the system file locking is used.
 124
 125             @return TRUE, if the stream was already part of the descriptor or could
 126                     be created as new item. FALSE otherwise.
 127          */
 128         sal_Bool addInputStream();
 129
 130         //---------------------------------------
 131         /** @short  it checks if the descriptor already has a valid
 132                     InputStream item and creates a new one, if not.
 133
 134             @descr  This method uses the current items of this MediaDescriptor,
 135                     to open the stream (as e.g. URL, ReadOnly, PostData etcpp.).
 136                     It creates a seekable stream and put it into the descriptor.
 137
 138                     A might existing InteractionHandler will be used automaticly,
 139                     to solve problems!
 140
 141                     In case of local file the system file locking is used based on
 142                     configuration settings.
 143
 144             @return TRUE, if the stream was already part of the descriptor or could
 145                     be created as new item. FALSE otherwise.
 146          */
 147         sal_Bool addInputStreamOwnLock();
 148
 149         //---------------------------------------
 150         /** @short  it checks if the descriptor describes a readonly stream.
 151
 152             @descr  The descriptor itself isnt changed doing so.
 153                     It's only checked if the stream seems to be based
 154                     of a real readonly file.
 155
 156             @Attention
 157                     We dont check the property "ReadOnly" here. Because
 158                     this property can be set from outside and overwrites
 159                     the readonly state of  the stream.
 160                     If e.g. the stream could be opened read/write ...
 161                     but "ReadOnly" property is set to TRUE, this means:
 162                     show a readonly UI on top of this read/write stream.
 163
 164             @return TRUE, if the stream must be interpreted as readonly ...
 165                     FALSE otherwise.
 166          */
 167         sal_Bool isStreamReadOnly() const;
 168
 169         //---------------------------------------
 170         /** Returns a value from the sequence contained in the property
 171             'ComponentData' of this media descriptor.
 172
 173             @descr  The property 'ComponentData' should be empty, or should
 174                 contain a value of type sequence<com.sun.star.beans.NamedValue>
 175                 or sequence<com.sun.star.beans.PropertyValue>.
 176
 177             @return  The value with the specified name, if existing in the
 178                 sequence of the 'ComponentData' property, otherwise an empty
 179                 Any.
 180          */
 181         ::com::sun::star::uno::Any getComponentDataEntry(
 182             const OUString& rName ) const;
 183
 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 ::com::sun::star::uno::Any& rValue );
 203
 204         //---------------------------------------
 205         /** Removes a value from the sequence contained in the property
 206             'ComponentData' of the media descriptor.
 207
 208             @descr  The property 'ComponentData' should be empty, or should
 209                 contain a value of type sequence<com.sun.star.beans.NamedValue>
 210                 or sequence<com.sun.star.beans.PropertyValue>. The value with
 211                 the passed name will be removed from the sequence, if existing.
 212
 213             @param rName  The name of the value to be removed from the sequence
 214                 of the 'ComponentData' property.
 215          */
 216         void clearComponentDataEntry(
 217             const OUString& rName );
 218
 219     //-------------------------------------------
 220     // helper
 221     private:
 222
 223         //---------------------------------------
 224         /** @short  tries to open a stream by using the given PostData stream.
 225
 226             @descr  The stream is used directly ...
 227
 228                     The MediaDescriptor itself is changed inside this method.
 229                     Means: the stream is added internal and not returned by a value.
 230
 231             @param  _rxPostData
 232                     the PostData stream.
 233
 234             @return TRUE if the stream could be added successfully.
 235                     Note: If FALSE is returned, the error was already handled inside!
 236
 237             @throw  [css::uno::RuntimeException]
 238                     if the MediaDescriptor seems to be invalid!
 239
 240             @throw  [css::lang::IllegalArgumentException]
 241                     if the given PostData stream is <NULL/>.
 242          */
 243         COMPHELPER_DLLPRIVATE sal_Bool impl_openStreamWithPostData(
 244             const ::com::sun::star::uno::Reference< ::com::sun::star::io::XInputStream >& _rxPostData
 245             )   throw(::com::sun::star::uno::RuntimeException);
 246
 247         //---------------------------------------
 248         /** @short  tries to open a stream by using the given URL.
 249
 250             @descr  First it tries to open the content in r/w mode (if its
 251                     allowed to do so). Only in case its not allowed or it failed
 252                     the stream will be tried to open in readonly mode.
 253
 254                     The MediaDescriptor itself is changed inside this method.
 255                     Means: the stream is added internal and not returned by a value.
 256
 257             @param  sURL
 258                     the URL for open.
 259
 260             @param  bLockFile
 261                     specifies whether the file should be locked
 262
 263             @return TRUE if the stream could be added successfully.
 264                     Note: If FALSE is returned, the error was already handled inside!
 265
 266             @throw  [css::uno::RuntimeException]
 267                     if the MediaDescriptor seems to be invalid!
 268          */
 269         COMPHELPER_DLLPRIVATE sal_Bool impl_openStreamWithURL(
 270             const OUString& sURL,
 271             sal_Bool bLockFile
 272             ) throw(::com::sun::star::uno::RuntimeException);
 273
 274         //---------------------------------------
 275         /** @short  some URL parts can make trouble for opening streams (e.g. jumpmarks.)
 276                     An URL should be "normalized" before its used.
 277
 278             @param  sURL
 279                     the original URL (e.g. including a jumpmark)
 280
 281             @return [string]
 282                     the "normalized" URL (e.g. without jumpmark)
 283          */
 284         COMPHELPER_DLLPRIVATE OUString impl_normalizeURL(const OUString& sURL);
 285
 286         //---------------------------------------
 287         /** @short  it checks if the descriptor already has a valid
 288                     InputStream item and creates a new one, if not.
 289
 290             @descr  This method uses the current items of this MediaDescriptor,
 291                     to open the stream (as e.g. URL, ReadOnly, PostData etcpp.).
 292                     It creates a seekable stream and put it into the descriptor.
 293
 294                     A might existing InteractionHandler will be used automaticly,
 295                     to solve problems!
 296
 297             @param  bLockFile
 298                     specifies whether the file should be locked
 299
 300             @return TRUE, if the stream was already part of the descriptor or could
 301                     be created as new item. FALSE otherwise.
 302          */
 303         COMPHELPER_DLLPRIVATE sal_Bool impl_addInputStream( sal_Bool bLockFile );
 304 };
 305
 306 } // namespace comphelper
 307
 308 #endif // _COMPHELPER_MEDIADESCRIPTOR_HXX_
 309
 310 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */