include/ucbhelper/providerhelper.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_UCBHELPER_PROVIDERHELPER_HXX
  21 #define INCLUDED_UCBHELPER_PROVIDERHELPER_HXX
  22
  23 #include <list>
  24 #include <com/sun/star/ucb/XContentProvider.hpp>
  25 #include <com/sun/star/lang/XServiceInfo.hpp>
  26 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  27 #include <com/sun/star/lang/XTypeProvider.hpp>
  28 #include <cppuhelper/weak.hxx>
  29
  30 #include <osl/mutex.hxx>
  31 #include <rtl/ref.hxx>
  32 #include <ucbhelper/macros.hxx>
  33 #include <ucbhelper/ucbhelperdllapi.h>
  34
  35
  36
  37 namespace com { namespace sun { namespace star { namespace ucb {
  38     class XPropertySetRegistry;
  39     class XPersistentPropertySet;
  40 } } } }
  41
  42 namespace ucbhelper_impl { struct ContentProviderImplHelper_Impl; }
  43
  44 namespace ucbhelper {
  45
  46
  47
  48 class ContentImplHelper;
  49 typedef rtl::Reference< ContentImplHelper > ContentImplHelperRef;
  50 typedef std::list< ContentImplHelperRef > ContentRefList;
  51
  52 /**
  53   * This is an abstract base class for implementations of the service
  54   * com.sun.star.ucb.ContentProvider. It provides contents derived from
  55   * class ucb::ContentImplHelper.
  56   *
  57   * Features of the base class implementation:
  58   * - standard interfaces ( XInterface, XTypeProvider, XServiceInfo )
  59   * - maintains a set of ContentImplHelper objects, which were created by
  60   *   the provider implementation. So there will be exactly one object for
  61   *   one Content Identifier.
  62   * - Provides access to the Additional Core PropertySet of a content.
  63   *   ( These set contains the properties added to a content using its
  64   *   XPropertyContainer interface )
  65   */
  66 class UCBHELPER_DLLPUBLIC ContentProviderImplHelper : public cppu::OWeakObject,
  67                                     public com::sun::star::lang::XTypeProvider,
  68                                     public com::sun::star::lang::XServiceInfo,
  69                                     public com::sun::star::ucb::XContentProvider
  70 {
  71     friend class ContentImplHelper;
  72
  73     ucbhelper_impl::ContentProviderImplHelper_Impl* m_pImpl;
  74
  75 protected:
  76     osl::Mutex m_aMutex;
  77     ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext >  m_xContext;
  78
  79 private:
  80     UCBHELPER_DLLPRIVATE void removeContent( ContentImplHelper* pContent );
  81
  82     UCBHELPER_DLLPRIVATE ::com::sun::star::uno::Reference<
  83         ::com::sun::star::ucb::XPropertySetRegistry >
  84     getAdditionalPropertySetRegistry();
  85
  86     UCBHELPER_DLLPRIVATE void cleanupRegisteredContents();
  87
  88 protected:
  89     /**
  90       * This method returns a content with the given id, if it already exists.
  91       * Use this method in your "queryContent" implementation to ensure unique
  92       * objects.
  93       *
  94       * @param  Identifier is the content identifier, for that an existing
  95       *         content object is requested.
  96       * @return the content with the given identifier, if it exists or 0, if it
  97       *         does not exist.
  98       */
  99     rtl::Reference< ContentImplHelper >
 100     queryExistingContent( const ::com::sun::star::uno::Reference<
 101                    ::com::sun::star::ucb::XContentIdentifier >& Identifier );
 102
 103     /**
 104       * This method returns a content with the given URL, if it already exists.
 105       *
 106       * @param  rURL is the URL ( content identifier string ), for that an
 107       *         existing content object is requested.
 108       * @return the content with the given URL, if it exists or 0, if it
 109       *         does not exist.
 110       */
 111     rtl::Reference< ContentImplHelper >
 112     queryExistingContent( const OUString& rURL );
 113
 114     /**
 115       * This method registers a newly created content instance with the
 116       * content provider. It should be called directly after creating a new
 117       * content instance. The provider can reuse a registered instance upon
 118       * subsedent requests for content instances with an idententifier
 119       * of a registered instance.
 120       * Note that the provider does not hold a hard reference on the
 121       * registered instance. If last external reference is gone, the provider
 122       * will remove the instance from its inventory of known instances.
 123       * Nothing will happen in case an already registered instance shall
 124       * be registered more than once.
 125       *
 126       * @param  the content instance that is to be registered.
 127      */
 128     void registerNewContent(
 129         const com::sun::star::uno::Reference<
 130             ::com::sun::star::ucb::XContent > & xContent );
 131
 132 public:
 133
 134
 135     // Contsruction/Destruction
 136
 137
 138     ContentProviderImplHelper(
 139                 const ::com::sun::star::uno::Reference<
 140                     ::com::sun::star::uno::XComponentContext >& rxContext );
 141     virtual ~ContentProviderImplHelper();
 142
 143
 144     // XInterface
 145     virtual css::uno::Any SAL_CALL queryInterface( const css::uno::Type & rType )
 146         throw( css::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 147     virtual void SAL_CALL acquire()
 148         throw() SAL_OVERRIDE;
 149     virtual void SAL_CALL release()
 150         throw() SAL_OVERRIDE;
 151
 152     // XTypeProvider
 153
 154
 155     virtual com::sun::star::uno::Sequence< sal_Int8 > SAL_CALL
 156     getImplementationId()
 157         throw( com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 158     virtual com::sun::star::uno::Sequence< com::sun::star::uno::Type > SAL_CALL
 159     getTypes()
 160         throw( com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 161
 162     // XServiceInfo
 163
 164
 165     virtual OUString SAL_CALL
 166     getImplementationName()
 167         throw( ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE = 0;
 168     virtual sal_Bool SAL_CALL
 169     supportsService( const OUString& ServiceName )
 170         throw( ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 171     virtual ::com::sun::star::uno::Sequence< OUString > SAL_CALL
 172     getSupportedServiceNames()
 173         throw( ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE = 0;
 174
 175
 176     // XContentProvider
 177
 178
 179     /**
 180       * This method returns a content with the requested id.
 181       *
 182       * The implementation should:
 183       *
 184       * - Check, whether the Identifier is valid ( URL syntax ).
 185       * - Use queryExistingContent(...) to determine, whether there exists
 186       *   already a content with the given id.
 187       * - Return the possibly existing content.Create and return a new
 188       *   content, otherwise
 189       */
 190     virtual ::com::sun::star::uno::Reference<
 191                 ::com::sun::star::ucb::XContent > SAL_CALL
 192     queryContent( const ::com::sun::star::uno::Reference<
 193                     ::com::sun::star::ucb::XContentIdentifier >& Identifier )
 194         throw( ::com::sun::star::ucb::IllegalIdentifierException,
 195                ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE = 0;
 196     virtual sal_Int32 SAL_CALL
 197     compareContentIds( const ::com::sun::star::uno::Reference<
 198                             ::com::sun::star::ucb::XContentIdentifier >& Id1,
 199                        const ::com::sun::star::uno::Reference<
 200                                ::com::sun::star::ucb::XContentIdentifier >& Id2 )
 201         throw( ::com::sun::star::uno::RuntimeException, std::exception ) SAL_OVERRIDE;
 202
 203
 204     // Non-interface methods.
 205
 206
 207     /**
 208       * This method returns a mutex, which protects the content list of the
 209       * provider. So you can prevent modifications of that list easily.
 210       *
 211       * @return the mutex.
 212       */
 213     osl::Mutex& getContentListMutex() { return m_aMutex; }
 214
 215     /**
 216       * This method fills a list with all contents existing at calling time.
 217       * Note: You may prevent modifications of the content list at any time
 218       * by acquiring the content list mutex of the provider.
 219       *
 220       * @param  rContents is the list to fill with the children.
 221       */
 222     void queryExistingContents( ContentRefList& rContents );
 223
 224     /**
 225       * This method returns the propertyset containing the Additional Core
 226       * Properties of a content.
 227       *
 228       * @param  rKey is the key for the propertyset.
 229       * @param  bCreate is a flag indicating whether the propertyset shall
 230       *         be created in case it does not exist.
 231       * @return the propertyset containing the Additional Core Properties.
 232       */
 233     ::com::sun::star::uno::Reference<
 234         com::sun::star::ucb::XPersistentPropertySet >
 235     getAdditionalPropertySet( const OUString& rKey, bool bCreate );
 236
 237     /**
 238       * This method renames the propertyset containing the Additional Core
 239       * Properties of a content.
 240       *
 241       * @param  rOldKey is the old key of the propertyset.
 242       * @param  rNewKey is the new key for the propertyset.
 243       * @param  bRecursive is a flag indicating whether propertysets for
 244       *         children described by rOldKey shall be renamed, too.
 245       * @return True, if the operation succeeded - False, otherwise.
 246       */
 247     bool renameAdditionalPropertySet( const OUString& rOldKey,
 248                                           const OUString& rNewKey,
 249                                           bool bRecursive );
 250
 251     /**
 252       * This method copies the propertyset containing the Additional Core
 253       * Properties of a content.
 254       *
 255       * @param  rSourceKey is the key of the source propertyset.
 256       * @param  rTargetKey is the key of the target propertyset.
 257       * @param  bRecursive is a flag indicating whether propertysets for
 258       *         children described by rSourceKey shall be copied, too.
 259       * @return True, if the operation succeeded - False, otherwise.
 260       */
 261     bool copyAdditionalPropertySet( const OUString& rSourceKey,
 262                                         const OUString& rTargetKey,
 263                                         bool bRecursive );
 264
 265     /**
 266       * This method removes the propertyset containing the Additional Core
 267       * Properties of a content.
 268       *
 269       * @param  rKey is the key of the propertyset.
 270       * @param  bRecursive is a flag indicating whether propertysets for
 271       *         children described by rOldKey shall be removed, too.
 272       * @return True, if the operation succeeded - False, otherwise.
 273       */
 274     bool removeAdditionalPropertySet( const OUString& rKey,
 275                                           bool bRecursive );
 276 };
 277
 278 } // namespace ucbhelper
 279
 280 #endif /* ! INCLUDED_UCBHELPER_PROVIDERHELPER_HXX */
 281
 282 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */