celix_bundle_activator.h File Reference

#include <stdlib.h>
#include "celix_bundle_context.h"
#include "celix_dependency_manager.h"
#include "celix_dm_component.h"
#include "celix_dm_service_dependency.h"
#include "celix_constants.h"

Include dependency graph for celix_bundle_activator.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	CELIX_BUNDLE_ACTIVATOR_EXPORT
#define	CELIX_GEN_BUNDLE_ACTIVATOR(actType, actStart, actStop)
	This macro generates the required bundle activator functions for C. More...

Functions
CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t	celix_bundleActivator_create (celix_bundle_context_t *ctx, void **userData)
	Called when this bundle is started so the bundle can create an instance for its activator. More...
CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t	celix_bundleActivator_start (void *userData, celix_bundle_context_t *ctx)
	Called when this bundle is started so the Framework can perform the bundle-specific activities necessary to start this bundle. More...
CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t	celix_bundleActivator_stop (void *userData, celix_bundle_context_t *ctx)
	Called when this bundle is stopped so the Framework can perform the bundle-specific activities necessary to stop the bundle. More...
CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t	celix_bundleActivator_destroy (void *userData, celix_bundle_context_t *ctx)
	Called when this bundle is stopped so the bundle can destroy the instance of its activator. More...

Macro Definition Documentation

CELIX_BUNDLE_ACTIVATOR_EXPORT

#define CELIX_BUNDLE_ACTIVATOR_EXPORT

CELIX_GEN_BUNDLE_ACTIVATOR

#define CELIX_GEN_BUNDLE_ACTIVATOR	(		actType,
			actStart,
			actStop
	)

This macro generates the required bundle activator functions for C.

This can be used to more type safe bundle activator entries.

The macro will create the following bundle activator functions:

• bundleActivator_create which allocates a pointer to the provided type.
• bundleActivator_start/stop which will call the respectively provided typed start/stop functions.
• bundleActivator_destroy will free the allocated for the provided type.

After the (optional) provided activator stop callback is called, the generated celix_bundleActivator_stop function will remove all components from the bundle's dependency manager (using `celix_dependencyManager_removeAllComponents). This will ensure that dependency manager components can be used without explicitly programming their removal and destroy functionality.

Parameters

actType	The activator type (e.g. 'struct shell_activator').
actStart	The optional activator actStart function with the following signature: celix_status_t (*)(<actType>*, celix_bundle_context_t*).
actStop	The optional activator actStop function with the following signature: celix_status_t (*)(<actType>*, celix_bundle_context_t*).

Function Documentation

celix_bundleActivator_create()

CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_create	(	celix_bundle_context_t *	ctx,
		void **	userData
	)

Called when this bundle is started so the bundle can create an instance for its activator.

The framework does not assume any type for the activator instance, this is implementation specific. The activator instance is handle as a void pointer by the framework, the implementation must cast it to the implementation specific type.

Parameters

	ctx	The execution context of the bundle being started.
[out]	userData	A pointer to the specific activator instance used by this bundle.

Returns

Status code indication failure or success:

• CELIX_SUCCESS when no errors are encountered.
• Any other status code will mark the bundle as stopped and the framework will remove this bundle's listeners, unregister all services, and release all services used by this bundle.

celix_bundleActivator_destroy()

CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_destroy	(	void *	userData,
		celix_bundle_context_t *	ctx
	)

Called when this bundle is stopped so the bundle can destroy the instance of its activator.

In general, this method should undo the work that the bundleActivator_create() function initialized.

This method must complete and return to its caller in a timely manner.

Parameters

userData	The activator instance to be used.
ctx	The execution context of the bundle being stopped.

Returns

Status code indication failure or success:

• CELIX_SUCCESS when no errors are encountered.
• Any other status code will mark the bundle as stopped and the framework will remove this bundle's listeners, unregister all services, and release all services used by this bundle.

celix_bundleActivator_start()

CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_start	(	void *	userData,
		celix_bundle_context_t *	ctx
	)

Called when this bundle is started so the Framework can perform the bundle-specific activities necessary to start this bundle.

This method can be used to register services or to allocate any resources that this bundle needs.

This method must complete and return to its caller in a timely manner.

Parameters

userData	The activator instance to be used.
ctx	The execution context of the bundle being started.

Returns

Status code indication failure or success:

• CELIX_SUCCESS when no errors are encountered.
• Any other status code will mark the bundle as stopped and the framework will remove this bundle's listeners, unregister all services, and release all services used by this bundle.

celix_bundleActivator_stop()

CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_stop	(	void *	userData,
		celix_bundle_context_t *	ctx
	)

Called when this bundle is stopped so the Framework can perform the bundle-specific activities necessary to stop the bundle.

In general, this method should undo the work that the bundleActivator_start() function started. There should be no active threads that were started by this bundle when this bundle returns. A stopped bundle must not call any Framework objects.

This method must complete and return to its caller in a timely manner.

Parameters

userData	The activator instance to be used.
ctx	The execution context of the bundle being stopped.

Returns

Status code indication failure or success:

• CELIX_SUCCESS when no errors are encountered.
• Any other status code will mark the bundle as stopped and the framework will remove this bundle's listeners, unregister all services, and release all services used by this bundle.