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