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