Apache Celix  2.4.0
Apache Celix is a framework for C, C++14 and C++17 to develop dynamic modular software applications using component and in-process service-oriented programming.
Macros | Functions
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
actTypeThe activator type (e.g. 'struct shell_activator').
actStartThe optional activator actStart function with the following signature: celix_status_t (*)(<actType>*, celix_bundle_context_t*).
actStopThe 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
ctxThe execution context of the bundle being started.
[out]userDataA 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
userDataThe activator instance to be used.
ctxThe 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
userDataThe activator instance to be used.
ctxThe 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
userDataThe activator instance to be used.
ctxThe 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.