Apache OpenOffice Wiki - User contributions [en]

Uno/Cpp/Tutorials/Introduction to Cpp Uno

2008-12-02T03:59:07Z

Gvb: /* Strings */

==Overview==
This document gives an introduction to the C++ mapping of UNO. You should have read the A guide to language independent UNO, before reading with this document. It is a good idea to look at the relevant source code after reading this document. Some C++ components which follow the the concepts explained below can be found in the stoc, io or remotebridges modules, for example.

TODO :
* Documentation of the exported symbols in the Components section

==Shared library overview==
[[Image:udk_baselibraries.gif|center]]

In the above diagram the (C) means C-linkage, (C++) means C++ linkage. For all libraries you will need a C++ compiler to build.

The base for all UDK-libraries is the sal-library, that contains all system abstractions and does not contain any UNO-specific data. The most commonly used C-functions can be accessed via C++ inline wrappers. This allows to call the functions from any other programming language. The salhelper-library offers additional base functionality, that could be implemented inline.

The cppu ( = C Plus Plus Uno) library is the core uno library. It offers methods to access the UNO type library and allows to generically create, copy and compare values of UNO data types. Additionally all bridges (= mappings + environments) are administered here.

msci_uno, sunpro5_uno and urp_uno are only examples for language binding libraries (MS VC++ 6, sunpro5 solaris).

The cppuhelper library is a C++ library, that contains some important base classes for components (see
[[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno#Bootstrapping_the_initial_component_context|below]]). C++ components are usually linked against cppuhelper.

==System abstraction layer (sal)==
The sal-library offers operating system dependent services behind one interface. The aim is to minimize, or eliminate, operating system dependent #ifdefs in libraries above sal. Further more basic features such as strings are implemented in sal. Sal exports only C-symbols, there are inline C++ wrappers for convenience where it is sensible.

===[[SDKCppLanguage#Files|File access]]===
<code>osl::FileBase</code> 
<code>osl::VolumeInfo</code> 
<code>osl::FileStatus</code> 
<code>osl::File</code> 
<code>osl::DirectoryItem</code> 
<code>osl::Directory</code> 

===[[SDKCppLanguage#Threads|Thread]] safe refcounting===
osl_incrementInterlockedCount and osl_decrementInterlockedCount allow to modify a thread safe 4 byte counter.

===Threads and thread synchronization===
<code>::osl::Mutex</code> 
<code>::osl::Condition</code> 
<code>::osl::Semaphore</code> 
<code>::osl::Thread(docu not yet available)</code> 

===Interprocess communication===
<code>::osl::Socket(docu not yet available)</code> 
<code>::osl::Pipe(docu not yet available)</code> 

===Strings===
The [[SDKCppLanguage#Strings|String]] classes in sal ( rtl::OUString for Unicode-strings and rtl::OString for byte strings) are C++ wrappers for refcounted immutable C-strings. The rtl::OUStringBuffer and rtl::OStringBuffer allow efficient concatenation of strings.

===Byte [[SDKCppLanguage#Sequences|sequence]]===
The ::rtl::ByteSequence is a C++ wrapper around C-functions for a refcounted piece of memory. The ByteSequence is binary compatible to com::sun::star::uno::Sequence< sal_Int8>, both can be cast into each other.

==C++ mapping of IDL-types==
The binary specification for the IDL to C++ mapping can be found [http://udk.openoffice.org/cpp/man/spec/cpp_spec.html here], where some typical use cases of the C++ mapping are shown.

===Interface references===
Interface references, see com::sun::star::uno::Reference-template, are used to hold interfaces. The reference constructor (ctor) acquires (increases the refcount by one) the interface and the destructor releases the interface.

Example 1:
{{:Uno/Cpp/Snippet/Object_Lifecycle}}

Example 2:
{{:Uno/Cpp/Snippet/Instantiate_a_Service}}

===Weak references===
In general every uno object allows to hold weak references on it (see OWeakObject). Weak references allow to retrieve a hard interface reference if the object has not been destroyed before.

Example:
{{:Uno/Cpp/Snippet/Dereference_a_WeakReference}}

===Sequence===
For every type in UNO exists another type, the [[SDKCppLanguage#Sequences|sequence]] < type >. In C++, this is managed by the Sequence template, which is a wrapper around a refcounted C-struct. The sequence follows a copy on modify strategy (if the refcount is larger than 1, the sequence is copy-constructed). The sequence can only be used with UNO-types, because it needs a getCppuType for the element type ( which are generated by the build environment).

Some basic examples how to use the template
<source lang="cpp">
{
// create an integer sequence with 3 elements,
// elements are defaulted to zero.
Sequence< sal_Int32 > seqInt( 3 );

// get a read write pointer (this method checks for
// the refcount and does a copy on demand).
// however, if you know, that the refcount is one
// ( as in this case, the sequence has just been
// constructed), you could avoid the check
// (which is a C-call overhead)
// by writing sal_Int32 *pArray =
// (sal_Int32*) seqInt.getConstArray();
sal_Int32 *pArray = seqInt.getArray();

// modify the members
pArray[0] = 4;
pArray[1] = 5;
pArray[2] = 3;
}

{
sal_Int32 sourceArray[3] = {3,5,3};

// result is the same as above, but initialises from a buffer.
Sequence< sal_Int32 > seqInt( sourceArray , 3 );
}

{

// construct a sequence of Property structs,
// the structs are default constructed
Sequence< Property > seqProperty(2);
seqProperty.getArray()[0].Name = OUString::createFromAscii( "A" );
seqProperty.getArray()[0].Handle = 0;
seqProperty.getArray()[1].Name = OUString::createFromAscii( "B" );
seqProperty.getArray()[1].Handle = 1;

// copy construct the sequence (The refcount is raised)
Sequence< Property > seqProperty2 = seqProperty;

// access a sequence
for( sal_Int32 i = 0 ; i < seqProperty.getLength() ; i ++ )
{
// Please NOTE : seqProperty.getArray() would also work, but
// it is very expensive, because a
// unnecessary copy construction
// of the sequence takes place.
printf( "%d\n" , seqProperty.getConstArray()[i] );
}
}
</source>

===Any===
The [[SDKCppLanguage#Any|Any]] is a generic container, that stores a type and a value. Here are some basic examples, how to you use the Any :
<source lang="cpp">
{
sal_Int32 i = 5;
OUString string = OUString::createFromAscii( "demo" );

Any aInt,aString;

// put an sal_Int32 into an any
aInt <<= i;

// put a string into an any
aString <<= string;

// extract an int out of an any
sal_Int32 i2;
if( aInt >>= i2 )
{
printf( "int successfully extracted %d!\n" , i2 );
}

// the any does no conversion from string to int during extraction,
// use the typeconverter service for theses purposes.
if( !( aString >>= i2 ) )
{
printf( "string could not be converted to an int\n" );
}
}
</source>

===Exception===
UNO exceptions can simply be thrown like C++ exceptions. Example :
<source lang="cpp">
void ArbitraryService::doSomething( const Any &a )
throws( IllegalArgumentException )
{
sal_Int32 i;
if( ! (a >>= i ) )
{
// a int was specified to be in the any
IllegalArgumentException exception;
exception.Message = OUString::createFromAscii(
"unexpected type in any" );
exception.ArgumentPosition = 0;
throw exception;
}
}
</source>

==The cppuhelper module==
cppuhelper contains important base classes for UNO-objects, a bootstrap mechanism for the initial component context (factory context) and some other objects. The cppuhelper and salhelper libraries are the only C++-linkage libraries within the UDK.

===Weak object===
The cppu::OWeakObject is the suggested minimum base class that every uno object should support. (see cppuhelper/weak.hxx). It implements a basic refcounting object and allows others to hold the object weak (see weak references).

Example of an uno-object, that uses OWeakObject as base class.
<source lang="cpp">
class OFileWriter : public OWeakObject, public XOutputStream
{
public:
OFileWriter( char *pcFile ) : m_f( fopen( pcFile , "w" ) )
{}
public: // XInterface implementation
virtual Any SAL_CALL queryInterface(
const ::com::sun::star::uno::Type& aType ) throw()
{
Any a = ::cppu::queryInterface(
aType, static_cast< XOutputStream * >( this ) );

if( a.hasValue() )
{
return a;
}

return OWeakObject::queryInterface( aType );
}
virtual void SAL_CALL acquire()
{ OWeakObject::acquire(); }
virtual void SAL_CALL release()
{ OWeakObject::release(); }

public: // XOutputStream implementation
virtual void SAL_CALL writeBytes(
const Sequence< sal_Int8 >& aData) throw ()
{
fwrite( aData.getConstArray() , 1 , aData.getLength() , m_f );
}
virtual void SAL_CALL flush(void) throw ()
{
fflush( m_f );
}

virtual void SAL_CALL closeOutput(void) throw ()
{
fclose( m_f );
}
private:
FILE *m_f;
};
</source>
The class implements an XOutputStream using stdc library. The constructor creates a file and stores the file handle in a class member.

The task of queryInterface is to return the correct interface reference for the requested type, therefore it must cast the this-pointer to the correct interface pointer. The task is simplified by the global queryInterface-template-method, which compares the requested type with the cast this-pointers. If they match, an any with the correct reference is returned, otherwise an empty (void) any is returned. If the latter case is true, the call is delegated to OWeakObject's queryInterface.

acquire and release are delegated to OWeakObject to resolve ambiguities.

The following three methods simply implement the XOutputStream interface. Note that error checking has been omitted to simplify the code (this is certainly a very poor XOutputSteam implementation).

The methods have been implemented inline to shorten the source. There is certainly no advantage in inlining virtual methods and should not be done in general.

The object is not scriptable because it does not support the XTypeProvider -interface.

===The Component helper===
cppu::OComponentHelper is the suggested base class for UNO-objects that must support the XComponent interface. The implementation(see cppuhelper/weak.hxx ) takes care of event listener administration and ensures correctly notifying all listeners in both possible cases (refcount drops to zero or dispose is called). OComponentHelper is derived from OWeakObject.

===The implementation helper===
The so called implementation helpers are an excellent template variation of the above base classes. The use can be best explained with a sample :
<source lang="cpp">
class OFileWriter : public WeakImplHelper1< XOutputStream >
{
public:
OFileWriter( char *pcFile ) : m_f( fopen( pcFile , "w" ) )
{}

public: // XOutputStream implementation
virtual void SAL_CALL writeBytes(const Sequence< sal_Int8 >& aData) throw ()
{
fwrite( aData.getConstArray() , 1 , aData.getLength() , m_f );
}
virtual void SAL_CALL flush() throw ()
{
fflush( m_f );
}

virtual void SAL_CALL closeOutput() throw ()
{
fclose( m_f );
}
private:
FILE *m_f;
};
</source>

The implementation helper templates fulfill two tasks:
* correct queryInterface implementation (using the template parameter and their base classes as possible interfaces to query for).
* correct XTypeProvider implementation, so that the object is accessible by scripting languages.

The helper exists in 4 variations
* WeakImplHelper : base class is OWeakObject
* WeakComponentImplHelper : base class is OWeakObject, implements the same stuff as OComponentHelper
* WeakAggImplHelper : base class is OWeakAggObject
* WeakAggComponentImplHelper : base class is OWeakAggObject, implements the same stuff as OComponentHelper

Add the number of interfaces, you wish to implement, to the helper name ( something like va_arg for templates would be really cool). The implementation helper have the disadvantage, that the code is not debugable (because most of the code is implemented in macros), they have the advantage, that the error prone queryInterface and XTypeProvider implementation are not done by every application developer again and again (this saves really lots of debugging sessions). So using the implementation helper is the proposed way to implement UNO-objects.

There are, nevertheless, situations where you can't use the implementation helper (for example if you must implement more than 10 interfaces or if you have to provide a more complex query interface).

===Weak aggregation object===
Deriving from cppu::OWeakAggObject makes your object able to be [http://udk.openoffice.org/common/man/concept/unointro.html#aggregation aggregated].
The propertyset helper
Use ::cppu::OPropertySetHelper as base class, if you want to implement XPropertySet interface. [...] to be continued. There is no implementation helper variant for OPropertySetHelper.

===The factory helper===
The factory helpers allows to create factories for objects. See [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno#Exported_symbols| exported symbols]] for a use case for them.

==UNO contexts==
===bootstrapping the initial component context (factory context)===
The initial startup of the UNO system requires some sophisticated [[UNO_registery_and_Bootstrapping#C.2B.2B_UNO_bootstrapping_via_defaultBootstrap_InitialComponentContext.28.29|Bootstrapping]] to get an initial component context (including a service manager) to proceed service instantiation. The context provides you a service manager instance.
The cppuhelper function below can be called to bootstrap an initial component context with service manager upon a given registry. This includes insertion of initial the following service factories:
* (registry) service manager
* shared lib loader
* simple registry
* nested registry
* implementation registration
* registry typedescription provider
* typedescription manager

;cppuhelper/bootstrap.hxx:
<source lang="cpp">
Reference< XComponentContext > SAL_CALL bootstrap_InitialComponentContext(
Reference< registry::XSimpleRegistry > const & xRegistry,
OUString const & rBootstrapPath = OUString() )
SAL_THROW( (Exception) );
</source>

The function reads out all /SINGLETONS entries out of the registry and inserts entries into the component context. The typedescription manager singleton is raised to deliver types to the cppu core typelib, too.
To handle registries in a flexible way, there are two helper functions to get a simple registry and nested registry implementation:

;cppuhelper/bootstrap.hxx:
<source lang="cpp">
Reference< registry::XSimpleRegistry > SAL_CALL createSimpleRegistry(
const OUString & rBootstrapPath = OUString() )
SAL_THROW( () );

Reference< registry::XSimpleRegistry > SAL_CALL createNestedRegistry(
const OUString & rBootstrapPath = OUString() )
SAL_THROW( () );
</source>

There is also another function to bootstrap the UNO system reading reading out of environment variables the way it is presented here.

;cppuhelper/bootstrap.hxx:
<source lang="cpp">
Reference< XComponentContext > SAL_CALL defaultBootstrap_InitialComponentContext()
SAL_THROW( (Exception) );
</source>

The context holds arbitrary values which are recommended to be prefixed by the implementation name of the component that acknowledges a value, e.g. if you want to set the cache size of the stoc typedescription manager, set: com.sun.star.comp.stoc.TypeDescriptionManager.CacheSize to n. All API singletons are directly accessible by their name.
When closing down the application, you have to manually dispose the component context, which disposes all singleton objects including the service manager. This has to be done, because the context holds a hard reference to its service manager as well as the service manager its default context (property "DefaultContext"). By default each new component context wrapping an existing one (delegating unknown property requests to it) should add itself as event listener to dispose itself when the previous one is disposed (that is chaining).

Alternatively, you can call the existing functions in servicefactory.hxx to bootstrap a service manager instance. But when closing down, it is mandatory to dispose the component context (service manager's "DefaultContext" property).

<source lang="cpp">
// get initial context
Reference< XComponentContext > xContext( defaultBootstrap_InitialComponentContext() );
OSL_ASSERT( xContext.is() );

// retrieve typedescription manager singleton
Reference< XHierarchicalNameAccess > xTDMgr;
OSL_VERIFY( xContext->getValueByName( OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.reflection.TypeDescriptionManager") ) ) >>= xTDMgr );

// easier: retrieve service manager singleton
Reference< XMultiComponentFactory > xSMgr( xContext->getServiceManager() );
/* same as:
Reference< XMultiComponentFactory > xSMgr;
OSL_VERIFY( xContext->getValueByName( OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.lang.ServiceManager") ) ) >>= xSMgr );
*/

// launch new typedescription manager instance with modified cache size,
// NOTICE: knowing the context cache size key is implementation detail
// of the raised component. Caching is no concept of the implementation
// and can thus be ignored by the implementation!

// look at cppuhelper/component_context.hxx:
Contextentry_Init aEntry;
aEntry.bLateInitService = false;
aEntry.name = OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.comp.stoc.TypeDescriptionManager.CacheSize") );
aEntry.value = makeAny( (sal_Int32)0xdb0 );
// create new context overriding cache size, rest is delegated to previous context
Reference< XComponentContext > xNewContext( createComponentContext(
&aEntry, 1, xContext );
Reference< XInterface > xNewTDMgr( xSMgr->createInstanceWithContext(
OUString( RTL_CONSTASCII_USTRINGPARAM(
"com.sun.star.reflection.TypeDescriptionManager") ), xNewContext ) );

...

Reference< XComponent > xComp( xContext, UNO_QUERY );
OSL_ASSERT( xComp.is() );
xComp->dispose();
</source>

===Setting/ Retrieving the Current Context===
The [http://udk.openoffice.org/common/man/concept/uno_contexts.html#current_context current (task/ thread) context] has to be manually set when launching a new thread. There is a pair of functions setting and getting the context in uno/current_context.h and uno/current_context.hxx:

;uno/current_context.h:
<source lang="cpp">
sal_Bool SAL_CALL uno_getCurrentContext(
void ** ppCurrentContext,
rtl_uString * pEnvTypeName, void * pEnvContext )
SAL_THROW_EXTERN_C();

sal_Bool SAL_CALL uno_setCurrentContext(
void * pCurrentContext,
rtl_uString * pEnvTypeName, void * pEnvContext )
SAL_THROW_EXTERN_C();
</source>

;uno/current_context.hxx:
<source lang="cpp">
namespace com { namespace sun { namespace star { namespace uno {

inline Reference< XCurrentContext > SAL_CALL getCurrentContext()
SAL_THROW( () );
inline bool SAL_CALL setCurrentContext( Reference< XCurrentContext > const & xContext )
SAL_THROW( () );

} } } }
</source>

;IDL interface:
<source lang="idl">
module com { module sun { module star { module uno {

interface XCurrentContext : com::sun::star::uno::XInterface
{
any getValueByName( [in] string Name );
};

}; }; }; };
</source>

The first pair of functions is independent of the callers UNO environment while the second is defining inline functions for a C++ caller (more convenient). You should take care with what is handled in this thread/task-local container.

==C++ components==
C++ [[Constructing_Components|components]] are implemented in shared libraries (or modules in OpenOffice.org). The implementation of a sample component is documented [[Uno/Cpp/Tutorials/component_tutorial| here]]. Each module must support some C-symbols, which the shared-library-loader uses as entry points to access the components.

===Exported symbols===
Each module must export 4 C functions to make the components available.

TODO: List the header files required to export these symbols

# component_getImplementationEnvironmentFunc
<source lang="cpp">
/**************************************************************
* Function to determine the environment of the implementation.
* If the environment is NOT session specific
* (needs no additional context), then this function
* should return the environment type name and leave ppEnv (0).
*
* @param ppEnvTypeName environment type name;
* string must be constant
* @param ppEnv function returns its environment
* if the environment is session specific,
* i.e. has special context
*/
typedef void (SAL_CALL * component_getImplementationEnvironmentFunc)(
const sal_Char ** ppEnvTypeName,uno_Environment ** ppEnv);
</source>
The loader uses this function to determine the native environment of the component. In general, the component simply returns the compiler environment name. This enables us to use modules compiled by different compilers in the same process, assuming that a C++ to UNO bridge exists for each compiler.
# component_getDescriptionFunc
<source lang="cpp">
/************************************************************
* Optional function to retrieve a component description.
*
* @return an XML formatted string containing a short
* component description
*/
typedef const sal_Char * (SAL_CALL * component_getDescriptionFunc)(void);
</source>
The function must return a string that contains the XML-description of the component. This allows generic tools (testtools, implementation repository browsers, etc.) to collect information about the module.
# component_writeInfoFunc
<source lang="cpp">
/**********************************************************
* Writes component registry info, at least writing the
* supported service names.
*
* @param pServiceManager a service manager
* (the type is XMultiServiceFactory
* to be used by the environment
* returned by
* component_getImplementationEnvironment)
* @param pRegistryKey a registry key
* (the type is XRegistryKey to be used
* by the environment returned by
* component_getImplementationEnvironment)
* @return true if everything went fine
*/
typedef sal_Bool (SAL_CALL * component_writeInfoFunc)(
void * pServiceManager, void * pRegistryKey );
</source>
This function is called by the service com.sun.star.registry.ImplementationRegistration. It passes an XMultiServiceFactory and an XRegistryKey interface pointer, which are already mapped into the modules environment. The function can now register all implementations and services into this registry key.
# component_getFactoryFunc
<source lang="cpp">
/*********************************************************
* Retrieves a factory to create component instances.
*
* @param pImplName desired implementation name
* @param pServiceManager a service manager
* (the type is XMultiServiceFactory
* to be used by the environment
* returned by
* component_getImplementationEnvironment)
* @param pRegistryKey a registry key
* (the type is XRegistryKey to be used
* by the environment returned by
* component_getImplementationEnvironment)
* @return acquired component factory
* (the type is XInterface to be used by the
* environment returned by
* component_getImplementationEnvironment)
*/
typedef void * (SAL_CALL * component_getFactoryFunc)(
const sal_Char * pImplName,
void * pServiceManager, void * pRegistryKey );
</source>
This function is usually called the first time a component needs to be instantiated. The function should return an acquired XInterface interface-pointer for the requested implementation name.

Example (the implementation of the service is not shown here):
<source lang="cpp">
#define IMPLEMENTATION_NAME "com.sun.star.comp.io.stm.Pipe"
const sal_Char SERVICE_NAME[] = "com.sun.star.io.Pipe";
Sequence< OUString > pipe_getSupportedServiceNames()
{
Sequence< OUString > seqNames(1);
seqNames.getArray()[0] =
OUString::createFromAscii( SERVICE_NAME );
return seqNames;
}

Reference< XInterface > SAL_CALL pipe_CreateInstance(
const Reference< XComponentContext > & xContext )
{
return Reference < XInterface >(
( OWeakObject * ) new OPipe(xContext) );
}

extern "C"
{

void SAL_CALL component_getImplementationEnvironment(
const sal_Char ** ppEnvTypeName, uno_Environment ** ppEnv )
{
*ppEnvTypeName = CPPU_CURRENT_LANGUAGE_BINDING_NAME;
}
//==================================================================
sal_Bool SAL_CALL component_writeInfo(
void * pServiceManager, void * pRegistryKey )
{
if (pRegistryKey)
{
Reference< XRegistryKey > xNewKey(
reinterpret_cast< XRegistryKey * >( pRegistryKey )->createKey(
OUString::createFromAscii(
"/" IMPLEMENTATION_NAME "/UNO/SERVICES" ) ) );

const Sequence< OUString > & rSNL = pipe_getSupportedServiceNames();
const OUString * pArray = rSNL.getConstArray();
for ( sal_Int32 nPos = rSNL.getLength(); nPos--; )
xNewKey->createKey( pArray[nPos] );

return sal_True;
}
return sal_False;
}
//===================================================================
void * SAL_CALL component_getFactory(
const sal_Char * pImplName,
void * pServiceManager, void * pRegistryKey )
{
void * pRet = 0;

if (pServiceManager &&
rtl_str_compare( pImplName, IMPLEMENTATION_NAME ) == 0)
{
Reference< XSingleComponentFactory > xFactory( createSingleComponentFactory(
reinterpret_cast< XMultiServiceFactory * >( pServiceManager ),
OUString::createFromAscii( IMPLEMENTATION_NAME ),
pipe_CreateInstance, pipe_getSupportedServiceNames() ) );

if (xFactory.is())
{
xFactory->acquire();
pRet = xFactory.get();
}
}

return pRet;
}
}
</source>
TODO: This is quite a lot of code. Let's roughly step through it. [...]

===Singletons / MultiInstance===
Every component has to be implemented as multi-instance, i.e. upon loading the library they can use the cppuhelper createSingleComponentFactory() as outlined above. The old functions createSingleFactory() etc. are deprecated and should be changed. One-instance components (using createOneInstanceFactory) are deprecated, too. The component implementation should not decide by itself whether it is one-instance. Instead of this, a component should explicitly retrieve shared objects (singletons) via its context. All singleton key name (context key names) are to specified in IDL, for example:
<source lang="idl">
module com { module sun { module star { module reflection {

singleton TypeDescriptionManager
{
service com::sun::star::reflection::TypeDescriptionManager;
};

}; }; }; };
</source>

===Independent components===
A component is called independent if it is only linked against UDK libraries. The aim is to have an application that only uses independent components. The only external thing they need is a service manager to instantiate other components.

===Component registration===
In general, every application has a registry (in OpenOffice, it is called applicat.rdb ). The applicat.rdb contains the definition of all types used in the application and information how to instantiate a component. This information is written into the rdb by the component itself using the above component_writeInfo function.

The service com.sun.star.registry.ImplementationRegistration can be used to register a shared library. The service exports the interface com.sun.star.registry.XImplementationRegistration, which offers the registerImplementation-method. The library name, the service name of the loader (in general com.sun.star.loader.SharedLibrary) and a reference to a XRegistryKey interface (where the data shall be written to) must all be passed to the method. If an empty reference is passed, the service uses the registry of the servicemanager.

There exists a command line tool for registration (regcomp), that does this (just call the tool without parameters to see its usage).

After the registration, the service is accessible directly through the servicemanager.

Note that if you have created new UNO-types in IDL, the types must also be merged into the applications registry (use the regmerge tool for this purpose).

==Common programming patterns==
* Threads and members Access to members in unguarded sections are in general not thread safe. Thus the following code and may crash (where m_xFoo is a reference to an UNO object).
<source lang="cpp">
//NOT THREAD SAFE :
MyComponent::do()
{
if( m_xFoo.is() )
m_xFoo->doSomething();
}

//THREAD SAFE :
MyComponent::do()
{
Reference < XFoo > xFoo;
{
MutexGuard guard( m_mutex );
xFoo = m_xFoo;
}
if( xFoo.is() )
xFoo->doSomething();
}
</source> Between the check of m_xFoo.is() and the call m_xFoo->doSomething(), the reference may be cleared by another thread or during the call of m_xFoo->doSomething() may be cleared, which can lead to the destruction of the UNO-object. The reference assignment is not thread safe, as it is not an atomic operation (the reference might be cleared by another thread, before the current thread reaches the osl_incrementInterlockedCount() function). Therefor each member access must be guarded. Note that this holds also for other refcounted objects such as strings, sequences, etc. This certainly implies performance overhead of locking a mutex. If you know, that a certain member can never be changed, it is correct not to guard access to this member. But keep in mind that your code should also be stable to small modifications. If you don't need the performance in that piece of code, you should always choose the safer method. Code must be in first place correct and in second place fast.

* Initialize static objects on demand If there is need for a static object, do not initialize it before main. This is a serious performance hit at application startup. Use wrapper functions to access static data instead, so that they are initialized on demand.

* Thread safe initializing static data - Initialization of non atomic static data, that is not initialized before main (see above) must be guarded. To make this efficient, do the following.
<source lang="cpp">
Mutex * getInitMutex()
{
static Mutex *pInitMutex = 0;
if( ! pInitMutex )
{
::osl::Guard guard( ::osl::Mutex::getGlobalMutex() );
if( ! pInitMutex )
{
static ::osl::Mutex initMutex;
pInitMutex = &initMutex;
}
}
return pInitMutex;
}

MyStaticData *getMyStaticDataImpl()
{
static MyStaticData staticData;
return &staticData;
}

static g_pMyStaticData * =0;
inline MyStaticData *getMyStaticData()
{
if( ! g_pMyStaticData )
{
::osl::Guard guard( getInitMutex() );
if( ! g_pMyStaticData )
{
g_pMyStaticData = getMyStaticDataImpl();
}
}
return g_pMyStaticData;
}
</source>
This looks a bit more complicated than it really is, lets step through it. The aim is to retrieve a pointer to the static data (here MyStaticData) as fast as possible (the first access can be slower, because these are only one time costs), so getMyStaticData is inline. If the data has been initialized before, then access is very fast (in fact a check to zero overhead, no function call). The construction of the static data should not be an inline function, because the current version of gcc on the Mac has problems with static data in inline functions. The mutex used to guard the initialization is also constructed in this example. The construction of the mutex is guarded by the ::osl::Mutex::getGlobalMutex(), one of the rare objects constructed before main. Why not use the global mutex directly for guarding ? The answer is that it can be done, if and ONLY if the constructor of MyStaticData does not call something you do not know. If the constructor does a UNO-call, which is bridged to another process, the reply for this call is dispatched in a different thread and this thread needs to initialize some static data of its own, then you have a deadlock (too many debugging sessions have been spent on this...!)

* DON'T USE MACROS - There are a lot of different opinions on this topic, but I want to stress this topic here : Do not use macros if there are other solutions (inline functions, inline template functions, const vars, etc.). Using macros generally has the following drawbacks:
** It is not type safe. The compiler does fewer checks, which results in finding bugs at runtime instead of finding them at compile time.
** The debugger does not know the symbols (e.g. strings, constants).
** If code is executed within macros, it is not debuggable.
** The code gets very difficult to read.

Code is read much more often read than it is written.

== See also ==
* [[Using_Cpp_with_the_OOo_SDK|Using C++ with the OOoSDK]]
* [[OpenOffice_filters_using_the_XML_based_file_format|OpenOffice filters using the XML based file format]]

[[Category:Uno]]
[[Category:Uno:Cpp]]
[[Category:Tutorial]]
[[Category:Cpp]]

Extensions development java

2008-12-02T03:51:12Z

Gvb:

{{Extensions}}

=== Java specific information for Extensions creation ===

=== Resources ===
* [[JavaEclipseTuto|Create UNO component in Java using Eclipse]]
To help you, there is an Eclipse plugin and a tutorial to use it. You can install the Eclipse plugin by using the updating site [http://cedric.bosdonnat.free.fr/ooeclipseintegration http://cedric.bosdonnat.free.fr/ooeclipseintegration].

This article is one of the [[OpenOffice.org_Developer_Article_Contest|Article Contest]] winners. [[Extensions#Translating_these_pages|Any translation]] is welcomed.

=== Tools ===
Tools which support the development of extensions:
* [[OpenOffice_NetBeans_Integration|OpenOffice NetBeans Integration]] provides wizards to create UNO components and client applications (based on the SDK and an office installation).
* The [http://development.openoffice.org/releases/2.0.4_sdk.html OpenOffice.org Software Development Kit](SDK) provides basic tools (like the idlc, javamaker) and some examples.

[[Category:Extensions]]

Extensions development

2008-12-02T03:34:38Z

Gvb:

{{Extensions}}
Developing extensions is an efficient way to bring value to OpenOffice.org without diving into core sources. Obviously all developers willing to [[Main_Page|develop at OpenOffice.org sources level]] are welcomed.

OpenOffice.org enables third party tools creation through UNO bridges, allowing using many languages.

The principle is to create UNO packages that can be listed in the OpenOffice.org [[Extensions_repository|Extensions repository]] and installed by end-users easily.

This section gives newcomers as well as experienced developers some hints for developing Extensions in various languages and provides tools and frameworks to facilitate that development.

Finally, popular Extensions may be integrated into OpenOffice.org, so it is important to follow common policies from beginning to ease this merging.

==== Starting in a language ====
Addons can be written in various languages. Each section gives starting information to help you create your addon. Each section is dedicated to a language. It deals with specific points concerning the Extensions aspect. Resources regarding the OpenOffice.org API can be found on the [http://api.openoffice.org API project] and the UNO bridge language issues are at [http://udk.openoffice.org UDK project]. The [http://wiki.services.openoffice.org/wiki/Documentation/DevGuide/OpenOffice.org_Developers_Guide OpenOffice.org Developer's Guide] is a valuable source of information as well.

The translations of these pages are welcomed and [[Extensions#Translating_these_pages|guidelines are available]].

* [[Extensions_development_python|Starting in Python]]
* [[Extensions_development_basic|Starting in Basic]] and [[Documentation/BASIC_Guide|Documentation BASIC Guide]]
* [[Extensions_development_java|Starting in Java]]
* [[Uno/Cpp/Tutorials/Introduction_to_Cpp_Uno|Introduction to C++ and UNO]] and [[Using_Cpp_with_the_OOo_SDK|Using C++ with OOoSDK]]
* [[Extensions_development_vfp|Starting in Visual FoxPro (French)]]
* [[Non-code_extensions|Non programmatic Extensions]]
* [[Extensions_packaging|Extensions packaging]]
* [[Extensions_Integration_into_Installation_Set|Extensions Integration into Installation Set]]
* [[Spellchecker_Integration_into_Installation_Set|Adding Spellchecker Extensions into Installation Set]]
* [[Filter_extensions|Import and Export filter extensions using code or xslt]]

==== Articles & Tutorials ====

* [[Framework/Article/Generic_UNO_Interfaces_for_complex_toolbar_controls|Generic UNO Interfaces for complex toolbar controls]]

* [[Framework/Article/Addon_Menu_Toolbar_Merging|Addon Menu Toolbar Merging]]

* [[Framework/Tutorial/Popup_Menu_Controller|Popup Menu Controller]]

* [[Framework/Tutorial/Statusbar_Controller|Statusbar Controller]]

==== Books on OpenOffice.org Basic Programming ====

* [http://www.amazon.com/OpenOffice-org-Macros-Explained-Andrew-Pitonyak/dp/1930919514/ OpenOffice.org Macros Explained] by Andrew Pitonyak
* [http://www.lulu.com/content/2905912 OpenOffice.org Basic Crash Course] by Dmitri Popov
* [http://www.amazon.com/Learn-OpenOffice-org-Spreadsheet-Macro-Programming/dp/1847190979/ Learn OpenOffice.org Spreadsheet Macro Programming] by Mark, Alexander Bain
* [http://www.amazon.de/Makros-OpenOffice-org-2-3-StarBasic-OpenOffice/dp/3836211114/ Makros in OpenOffice.org 2.3] von Thomas Krumbein (in German)
* [http://www.amazon.fr/Programmation-OpenOffice-org-Macros-OOoBasic-API/dp/2212117639/ Programmation OpenOffice.org 2] de Bernard Marcelly, Laurent Godard (in French)

==== Tools & Frameworks ====

* [http://codesnippets.services.openoffice.org Code snippets available in many languages]
* [[API/Samples|Code snippets in the Wiki]]
* [[Extensions_development_translation|Translation framework]]
* [[Extensions_Packager|Extensions Packager]] - BasicAddonBuilder - Extension Compiler
* Predefined wizards
* [[Extensions_introspection|Introspection Tools]]: discover the API
* [[OpenOffice_Eclipse_Integration|OpenOffice.org Eclipse Integration]] - OpenOffice.org development with Eclipse
* [[OpenOffice_NetBeans_Integration|OpenOffice.org NetBeans Integration]] - plug-in for NetBeans providing some nice features to simplify the development with and for OpenOffice.org (highlevel wizards, UNOIDL and xcu syntax highlighting, code completion, integrated API reference, ...)
* [[Extension_Development_with_IntelliJ_IDEA|Extension Development with IntelliJ IDEA]]: simple introduction how you can use the IntelliJ IDEA to develop OpenOffice.org extensions.
* [[OpenOffice_Maven2_Integration|OpenOffice.org Maven 2 integration]] - Maven plugin to build OpenOffice.org extensions.

==== Best Practices ====
* [[Extensions_best_practices|How to write OO.o GUI Extensions today]]

==== Project: Enhancing the Extensions Infrastructure of OpenOffice.org ====
* [[Extensions_improvements_proposal|Project Proposal (agreed by the Community June 2006)]]
* [[Extensions_improvements_plan_and_status|Project Status]]

==== Improving the Extension Manager ====
* [[Extensions_feature_ideas|Feature ideas]]
[[Category:Extensions]]