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