include/cppuhelper/factory.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 #ifndef _CPPUHELPER_FACTORY_HXX_
  20 #define _CPPUHELPER_FACTORY_HXX_
  21
  22 #include <rtl/ustring.hxx>
  23 #include <uno/dispatcher.h>
  24 #include <rtl/unload.h>
  25
  26 #include <com/sun/star/uno/XComponentContext.hpp>
  27 #include <com/sun/star/lang/XSingleComponentFactory.hpp>
  28 #include <com/sun/star/lang/XSingleServiceFactory.hpp>
  29 #include <com/sun/star/lang/XMultiServiceFactory.hpp>
  30 #include <com/sun/star/registry/XRegistryKey.hpp>
  31 #include "cppuhelperdllapi.h"
  32
  33 //##################################################################################################
  34
  35 #define COMPONENT_GETENV            "component_getImplementationEnvironment"
  36 #define COMPONENT_GETENVEXT         "component_getImplementationEnvironmentExt"
  37 #define COMPONENT_GETDESCRIPTION    "component_getDescription"
  38 #define COMPONENT_WRITEINFO         "component_writeInfo"
  39 #define COMPONENT_GETFACTORY        "component_getFactory"
  40
  41 typedef struct _uno_Environment uno_Environment;
  42
  43 /** Function pointer declaration.
  44     Function determines the environment of the component implementation, i.e. which compiler
  45     compiled it. If the environment is NOT session specific (needs no additional context),
  46     then this function should return the environment type name and leave ppEnv (to 0).
  47
  48     @param ppEnvTypeName environment type name; string must be constant
  49     @param ppEnv function returns its environment if the environment is session specific,
  50                  i.e. has special context
  51 */
  52 typedef void (SAL_CALL * component_getImplementationEnvironmentFunc)(
  53     const sal_Char ** ppEnvTypeName, uno_Environment ** ppEnv );
  54
  55 /** Function pointer declaration.
  56     Function determines the environment of the component implementation, i.e. the compiler.
  57     If the environment is NOT session specific (needs no additional context),
  58     then this function should return the environment type name and leave ppEnv (to 0).
  59
  60     @param ppEnvTypeName environment type name; string must be a constant
  61     @param ppEnv         function returns an environment if the environment is session specific,
  62                          i.e. has special context
  63     @param pImplName
  64 */
  65 typedef void (SAL_CALL * component_getImplementationEnvironmentExtFunc)(
  66     sal_Char        const ** ppEnvTypeName,
  67     uno_Environment       ** ppEnv,
  68     sal_Char        const  * pImplName,
  69     uno_Environment        * pTargetEnv
  70 );
  71
  72 /** Function pointer declaration.
  73     Function retrieves a component description.
  74
  75     @return an XML formatted string containing a short component description
  76     @deprecated
  77 */
  78 typedef const sal_Char * (SAL_CALL * component_getDescriptionFunc)(void);
  79
  80 /** Function pointer declaration.
  81
  82     @deprecated component_writeInfo should no longer be used in new components
  83
  84     Function writes component registry info, at least writing the supported service names.
  85
  86     @param pServiceManager
  87     a service manager (the type is an XMultiServiceFactory that can be used
  88     by the environment returned by component_getImplementationEnvironment)
  89     @param pRegistryKey a registry key
  90     (the type is XRegistryKey that can be used by the environment
  91     returned by component_getImplementationEnvironment)
  92     @return true if everything went fine
  93 */
  94 typedef sal_Bool (SAL_CALL * component_writeInfoFunc)(
  95     void * pServiceManager, void * pRegistryKey );
  96
  97 /** Function pointer declaration.
  98     Retrieves a factory to create component instances.
  99
 100    @param pImplName
 101    desired implementation name
 102    @param pServiceManager
 103    a service manager (the type is XMultiServiceFactory that can be used by the environment
 104    returned by component_getImplementationEnvironment)
 105    @param pRegistryKey
 106    a registry key (the type is XRegistryKey that can be used by the environment
 107    returned by component_getImplementationEnvironment)
 108    @return acquired component factory
 109    (the type is lang::XSingleComponentFactory or lang::XSingleServiceFactory to be used by the
 110    environment returned by component_getImplementationEnvironment)
 111 */
 112 typedef void * (SAL_CALL * component_getFactoryFunc)(
 113     const sal_Char * pImplName, void * pServiceManager, void * pRegistryKey );
 114
 115 //##################################################################################################
 116
 117 namespace cppu
 118 {
 119
 120 /** Function pointer declaration.
 121     Function creates component instance passing the component context to be used.
 122
 123     @param xContext component context to be used
 124     @return component instance
 125 */
 126 typedef ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >(
 127     SAL_CALL * ComponentFactoryFunc)(
 128         ::com::sun::star::uno::Reference< ::com::sun::star::uno::XComponentContext > const & xContext )
 129     SAL_THROW( (::com::sun::star::uno::Exception) );
 130
 131 /** Creates a single component factory supporting the XSingleComponentFactory interface.
 132
 133     @param fptr function pointer for instanciating the object
 134     @param rImplementationName implementation name of service
 135     @param rServiceNames supported services
 136     @param pModCount a backwards-compatibility remainder of a removed library
 137            unloading feature; always set to null
 138 */
 139 CPPUHELPER_DLLPUBLIC ::com::sun::star::uno::Reference< ::com::sun::star::lang::XSingleComponentFactory >
 140 SAL_CALL createSingleComponentFactory(
 141     ComponentFactoryFunc fptr,
 142     ::rtl::OUString const & rImplementationName,
 143     ::com::sun::star::uno::Sequence< ::rtl::OUString > const & rServiceNames,
 144     rtl_ModuleCount * pModCount = 0 )
 145     SAL_THROW(());
 146
 147 /** Creates a single service factory which holds the instance created only once.
 148
 149     @param fptr function pointer for instanciating the object
 150     @param rImplementationName implementation name of service
 151     @param rServiceNames supported services
 152     @param pModCount a backwards-compatibility remainder of a removed library
 153            unloading feature; always set to null
 154
 155     @see createSingleComponentFactory
 156 */
 157 CPPUHELPER_DLLPUBLIC ::com::sun::star::uno::Reference< ::com::sun::star::lang::XSingleComponentFactory > SAL_CALL
 158 createOneInstanceComponentFactory(
 159     ComponentFactoryFunc fptr,
 160     ::rtl::OUString const & rImplementationName,
 161     ::com::sun::star::uno::Sequence< ::rtl::OUString > const & rServiceNames,
 162     rtl_ModuleCount * pModCount = 0 )
 163     SAL_THROW(());
 164
 165 /** Deprecated.  The type of the instanciate function used as argument of the create*Fcatory functions.
 166
 167     @see createSingleFactory
 168     @see createOneInstanceFactory
 169     @deprecated
 170 */
 171 typedef ::com::sun::star::uno::Reference< ::com::sun::star::uno::XInterface >(SAL_CALL * ComponentInstantiation)(
 172     const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory > & rServiceManager );
 173
 174 /** Deprecated.  Creates a single service factory.
 175
 176     @param rServiceManager      the service manager used by the implementation.
 177     @param rImplementationName  the implementation name. An empty string is possible.
 178     @param pCreateFunction      the function pointer to create an object.
 179     @param rServiceNames        the service supported by the implementation.
 180     @param pModCount a backwards-compatibility remainder of a removed library
 181            unloading feature; always set to null.
 182     @return a factory that support the interfaces XServiceProvider, XServiceInfo
 183     XSingleServiceFactory and XComponent.
 184
 185     @see createOneInstanceFactory
 186     @deprecated
 187 */
 188 CPPUHELPER_DLLPUBLIC ::com::sun::star::uno::Reference< ::com::sun::star::lang::XSingleServiceFactory > SAL_CALL
 189 createSingleFactory(
 190     const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory > & rServiceManager,
 191     const ::rtl::OUString & rImplementationName,
 192     ComponentInstantiation pCreateFunction,
 193     const ::com::sun::star::uno::Sequence< ::rtl::OUString > & rServiceNames,
 194     rtl_ModuleCount * pModCount = 0  )
 195     SAL_THROW(());
 196
 197 /** Deprecated.  Creates a factory wrapping another one.
 198     This means the methods of the interfaces XServiceProvider, XServiceInfo and
 199     XSingleServiceFactory are forwarded.
 200     @attention
 201     The XComponent interface is not supported!
 202
 203     @param rServiceManager      the service manager used by the implementation.
 204     @param rFactory             the wrapped service factory.
 205     @return a factory that support the interfaces XServiceProvider, XServiceInfo
 206     XSingleServiceFactory.
 207
 208     @see createSingleFactory
 209     @deprecated
 210 */
 211 CPPUHELPER_DLLPUBLIC ::com::sun::star::uno::Reference< ::com::sun::star::lang::XSingleServiceFactory > SAL_CALL
 212 createFactoryProxy(
 213     const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory > & rServiceManager,
 214     const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XSingleServiceFactory > & rFactory )
 215     SAL_THROW(());
 216
 217 /** Deprecated.  Creates a single service factory which holds the instance created only once.
 218
 219     @param rServiceManager      the service manager used by the implementation.
 220     @param rComponentName       the implementation name. An empty string is possible.
 221     @param pCreateFunction      the function pointer to create an object.
 222     @param rServiceNames        the service supported by the implementation.
 223     @param pModCount a backwards-compatibility remainder of a removed library
 224            unloading feature; always set to null.
 225     @return a factory that support the interfaces XServiceProvider, XServiceInfo
 226     XSingleServiceFactory and XComponent.
 227
 228     @see createSingleFactory
 229     @deprecated
 230 */
 231 CPPUHELPER_DLLPUBLIC ::com::sun::star::uno::Reference< ::com::sun::star::lang::XSingleServiceFactory > SAL_CALL
 232 createOneInstanceFactory(
 233     const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory > & rServiceManager,
 234     const ::rtl::OUString & rComponentName,
 235     ComponentInstantiation pCreateFunction,
 236     const ::com::sun::star::uno::Sequence< ::rtl::OUString > & rServiceNames,
 237     rtl_ModuleCount * pModCount = 0  )
 238     SAL_THROW(());
 239
 240 /** Deprecated.  Creates a single service factory based on a registry.
 241
 242     @param rServiceManager      the service manager used by the implementation.
 243     @param rImplementationName  the implementation name. An empty string is possible.
 244     @param rImplementationKey   the registry key of the implementation section.
 245     @return a factory that support the interfaces XServiceProvider, XServiceInfo
 246     XSingleServiceFactory and XComponent.
 247     @deprecated
 248 */
 249 CPPUHELPER_DLLPUBLIC ::com::sun::star::uno::Reference< ::com::sun::star::lang::XSingleServiceFactory > SAL_CALL
 250 createSingleRegistryFactory(
 251     const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory > & rServiceManager,
 252     const ::rtl::OUString & rImplementationName,
 253     const ::com::sun::star::uno::Reference< ::com::sun::star::registry::XRegistryKey > & rImplementationKey )
 254     SAL_THROW(());
 255
 256 /** Deprecated.  Creates a single service factory which holds the instance created only once
 257     based on a registry.
 258
 259     @param rServiceManager      the service manager used by the implementation.
 260     @param rComponentName       the implementation name. An empty string is possible.
 261     @param rImplementationKey   the registry key of the implementation section.
 262     @return a factory that support the interfaces XServiceProvider, XServiceInfo
 263     XSingleServiceFactory and XComponent.
 264
 265     @see createSingleRegistryFactory
 266     @deprecated
 267 */
 268 CPPUHELPER_DLLPUBLIC ::com::sun::star::uno::Reference< ::com::sun::star::lang::XSingleServiceFactory > SAL_CALL
 269 createOneInstanceRegistryFactory(
 270     const ::com::sun::star::uno::Reference< ::com::sun::star::lang::XMultiServiceFactory > & rServiceManager,
 271     const ::rtl::OUString & rComponentName,
 272     const ::com::sun::star::uno::Reference< ::com::sun::star::registry::XRegistryKey > & rImplementationKey )
 273     SAL_THROW(());
 274
 275 }
 276
 277 #endif
 278
 279 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */