Apache Celix  latest
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.
Functions
celix_framework.h File Reference

The Celix Framework API. More...

#include <stdarg.h>
#include "celix_types.h"
#include "celix_properties.h"
#include "celix_log_level.h"
#include "celix_array_list.h"
#include "celix_framework_export.h"
Include dependency graph for celix_framework.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

const CELIX_FRAMEWORK_EXPORT char * celix_framework_getUUID (const celix_framework_t *fw)
 Returns the framework UUID. This is unique for every created framework and will not be the same if the process is restarted. More...
 
CELIX_FRAMEWORK_EXPORT celix_bundle_context_t * celix_framework_getFrameworkContext (const celix_framework_t *fw)
 Returns the framework bundle context. This is the same as a 'normal' bundle context and can be used to register, use and track services. The only difference is that the framework is the bundle. More...
 
CELIX_FRAMEWORK_EXPORT celix_bundle_t * celix_framework_getFrameworkBundle (const celix_framework_t *fw)
 Returns the framework bundle. This is the same as a 'normal' bundle, expect that this bundle cannot be uninstalled and the celix_bundle_getEntry return a entries relative from the working directory. More...
 
CELIX_FRAMEWORK_EXPORT size_t celix_framework_useBundles (celix_framework_t *fw, bool includeFrameworkBundle, void *callbackHandle, void(*use)(void *handle, const celix_bundle_t *bnd))
 Use the currently installed bundles. The provided callback will be called for all the currently installed bundles. More...
 
CELIX_FRAMEWORK_EXPORT size_t celix_framework_useActiveBundles (celix_framework_t *fw, bool includeFrameworkBundle, void *callbackHandle, void(*use)(void *handle, const celix_bundle_t *bnd))
 Use the currently active bundles. The provided callback will be called for all the currently active bundles. The bundle state is guaranteed to be active during the callback. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_framework_useBundle (celix_framework_t *fw, bool onlyActive, long bndId, void *callbackHandle, void(*use)(void *handle, const celix_bundle_t *bnd))
 Use the bundle with the provided bundle id The provided callback will be called if the bundle is found. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_framework_isBundleInstalled (celix_framework_t *fw, long bndId)
 Check whether a bundle is installed. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_framework_isBundleActive (celix_framework_t *fw, long bndId)
 Check whether the bundle is active. More...
 
CELIX_FRAMEWORK_EXPORT long celix_framework_installBundle (celix_framework_t *fw, const char *bundleLoc, bool autoStart)
 Install and optional start a bundle. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_framework_uninstallBundle (celix_framework_t *fw, long bndId)
 Uninstall the bundle with the provided bundle id. If needed the bundle will be stopped first. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_framework_unloadBundle (celix_framework_t *fw, long bndId)
 Unload the bundle with the provided bundle id. If needed the bundle will be stopped first. Will silently ignore bundle ids < 0. Note that unloaded bundle is kept in bundle cache and can be reloaded with the celix_framework_installBundle function. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_framework_updateBundle (celix_framework_t *fw, long bndId, const char *updatedBundleUrl)
 Update the bundle with the provided bundle id. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_framework_stopBundle (celix_framework_t *fw, long bndId)
 Stop the bundle with the provided bundle id. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_framework_startBundle (celix_framework_t *fw, long bndId)
 Start the bundle with the provided bundle id. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT long celix_framework_installBundleAsync (celix_framework_t *fw, const char *bundleLoc, bool autoStart)
 Install and optional start a bundle async. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_updateBundleAsync (celix_framework_t *fw, long bndId, const char *updatedBundleUrl)
 Update the bundle with the provided bundle id async. More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_uninstallBundleAsync (celix_framework_t *fw, long bndId)
 Uninstall the bundle with the provided bundle id async. If needed the bundle will be stopped first. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_unloadBundleAsync (celix_framework_t *fw, long bndId)
 Unload the bundle with the provided bundle id async. If needed the bundle will be stopped first. Will silently ignore bundle ids < 0. Note that unloaded bundle is kept in bundle cache and can be reloaded with the celix_framework_installBundle function. The bundle will be unloaded on a separate spawned thread. More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_stopBundleAsync (celix_framework_t *fw, long bndId)
 Stop the bundle with the provided bundle id async. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_startBundleAsync (celix_framework_t *fw, long bndId)
 Start the bundle with the provided bundle id async. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT celix_array_list_t * celix_framework_listBundles (celix_framework_t *framework)
 List the installed and started bundle ids. The bundle ids does not include the framework bundle (bundle id CELIX_FRAMEWORK_BUNDLE_ID). More...
 
CELIX_FRAMEWORK_EXPORT celix_array_list_t * celix_framework_listInstalledBundles (celix_framework_t *framework)
 List the installed bundle ids. The bundle ids does not include the framework bundle (bundle id CELIX_FRAMEWORK_BUNDLE_ID). More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_setLogCallback (celix_framework_t *fw, void *logHandle, void(*logFunction)(void *handle, celix_log_level_e level, const char *file, const char *function, int line, const char *format, va_list formatArgs))
 Sets the log function for this framework. Default the celix framework will log to stdout/stderr. More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_waitForEmptyEventQueue (celix_framework_t *fw)
 Wait until the framework event queue is empty. More...
 
CELIX_FRAMEWORK_EXPORT celix_status_t celix_framework_waitForEmptyEventQueueFor (celix_framework_t *fw, double timeoutInSeconds)
 Wait until the framework event queue is empty or the provided period is reached. More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_waitUntilNoEventsForBnd (celix_framework_t *fw, long bndId)
 wait until all events from the event queue for the bundle identified by the bndId are processed. More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_waitUntilNoPendingRegistration (celix_framework_t *fw)
 wait until all pending service registration are processed. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_framework_isCurrentThreadTheEventLoop (celix_framework_t *fw)
 Returns whether the current thread is the Celix framework event loop thread. More...
 
CELIX_FRAMEWORK_EXPORT long celix_framework_fireGenericEvent (celix_framework_t *fw, long eventId, long bndId, const char *eventName, void *processData, void(*processCallback)(void *data), void *doneData, void(*doneCallback)(void *doneData))
 Fire a generic event. The event will be added to the event loop and handled on the event loop thread. More...
 
CELIX_FRAMEWORK_EXPORT long celix_framework_nextEventId (celix_framework_t *fw)
 Get the next event id. More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_waitForGenericEvent (celix_framework_t *fw, long eventId)
 Wait until a event from the event queue with the provided event id is completely handled. This function will directly return if the provided event id is not in the event loop (already done or never issued). More...
 
CELIX_FRAMEWORK_EXPORT void celix_framework_waitForStop (celix_framework_t *framework)
 Wait until the framework is stopped. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_framework_isEventQueueEmpty (celix_framework_t *fw)
 Check if the event queue is empty. More...
 

Detailed Description

The Celix Framework API.

The Celix Framework API provides the functionality to create and destroy a Celix framework instance.

The Celix framework instance provides the following functionality:

Note
The Celix framework instance is thread safe.

Function Documentation

◆ celix_framework_fireGenericEvent()

CELIX_FRAMEWORK_EXPORT long celix_framework_fireGenericEvent ( celix_framework_t *  fw,
long  eventId,
long  bndId,
const char *  eventName,
void *  processData,
void(*)(void *data)  processCallback,
void *  doneData,
void(*)(void *doneData)  doneCallback 
)

Fire a generic event. The event will be added to the event loop and handled on the event loop thread.

The process callback should be fast and non-blocking, otherwise the framework event queue will be blocked and framework will not function properly.

if bndId >=0 the bundle usage count will be increased while the event is not yet processed or finished processing. The name is expected to be const char* valid during til the event is finished processing.

if eventId >=0 this will be used, otherwise a new event id will be generated return eventId

◆ celix_framework_getFrameworkBundle()

CELIX_FRAMEWORK_EXPORT celix_bundle_t* celix_framework_getFrameworkBundle ( const celix_framework_t *  fw)

Returns the framework bundle. This is the same as a 'normal' bundle, expect that this bundle cannot be uninstalled and the celix_bundle_getEntry return a entries relative from the working directory.

Parameters
fwThe framework
Returns
A pointer to the bundle of the framework or NULL if something went wrong.

◆ celix_framework_getFrameworkContext()

CELIX_FRAMEWORK_EXPORT celix_bundle_context_t* celix_framework_getFrameworkContext ( const celix_framework_t *  fw)

Returns the framework bundle context. This is the same as a 'normal' bundle context and can be used to register, use and track services. The only difference is that the framework is the bundle.

Parameters
fwThe framework
Returns
A pointer to the bundle context of the framework or NULL if something went wrong.

◆ celix_framework_getUUID()

const CELIX_FRAMEWORK_EXPORT char* celix_framework_getUUID ( const celix_framework_t *  fw)

Returns the framework UUID. This is unique for every created framework and will not be the same if the process is restarted.

◆ celix_framework_installBundle()

CELIX_FRAMEWORK_EXPORT long celix_framework_installBundle ( celix_framework_t *  fw,
const char *  bundleLoc,
bool  autoStart 
)

Install and optional start a bundle. Will silently ignore bundle ids < 0.

Parameters
fwThe Celix framework
bundleLocThe bundle location to the bundle zip file.
autoStartIf the bundle should also be started.
Returns
the bundleId (>= 0) or < 0 if the bundle could not be installed and possibly started.

◆ celix_framework_installBundleAsync()

CELIX_FRAMEWORK_EXPORT long celix_framework_installBundleAsync ( celix_framework_t *  fw,
const char *  bundleLoc,
bool  autoStart 
)

Install and optional start a bundle async. Will silently ignore bundle ids < 0.

If the bundle needs to be started this will be done a separate spawned thread.

Parameters
fwThe Celix framework
bundleLocThe bundle location to the bundle zip file.
autoStartIf the bundle should also be started.
Returns
The bundle id of the installed bundle or -1 if the bundle could not be installed

◆ celix_framework_isBundleActive()

CELIX_FRAMEWORK_EXPORT bool celix_framework_isBundleActive ( celix_framework_t *  fw,
long  bndId 
)

Check whether the bundle is active.

Parameters
fwThe Celix framework
bndIdThe bundle id to check
Returns
true if the bundle is installed and active.

◆ celix_framework_isBundleInstalled()

CELIX_FRAMEWORK_EXPORT bool celix_framework_isBundleInstalled ( celix_framework_t *  fw,
long  bndId 
)

Check whether a bundle is installed.

Parameters
fwThe Celix framework
bndIdThe bundle id to check
Returns
true if the bundle is installed.

◆ celix_framework_isCurrentThreadTheEventLoop()

CELIX_FRAMEWORK_EXPORT bool celix_framework_isCurrentThreadTheEventLoop ( celix_framework_t *  fw)

Returns whether the current thread is the Celix framework event loop thread.

◆ celix_framework_isEventQueueEmpty()

CELIX_FRAMEWORK_EXPORT bool celix_framework_isEventQueueEmpty ( celix_framework_t *  fw)

Check if the event queue is empty.

◆ celix_framework_listBundles()

CELIX_FRAMEWORK_EXPORT celix_array_list_t* celix_framework_listBundles ( celix_framework_t *  framework)

List the installed and started bundle ids. The bundle ids does not include the framework bundle (bundle id CELIX_FRAMEWORK_BUNDLE_ID).

Parameters
frameworkThe Celix framework.
Returns
A array with bundle ids (long). The caller is responsible for destroying the array.

◆ celix_framework_listInstalledBundles()

CELIX_FRAMEWORK_EXPORT celix_array_list_t* celix_framework_listInstalledBundles ( celix_framework_t *  framework)

List the installed bundle ids. The bundle ids does not include the framework bundle (bundle id CELIX_FRAMEWORK_BUNDLE_ID).

Parameters
frameworkThe Celix framework.
Returns
A array with bundle ids (long). The caller is responsible for destroying the array.

◆ celix_framework_nextEventId()

CELIX_FRAMEWORK_EXPORT long celix_framework_nextEventId ( celix_framework_t *  fw)

Get the next event id.

This can be used to ensure celix_framework_waitForGenericEvent can be used to wait for an event. The returned event id will not be used by the framework itself unless followed up with a celix_framework_fireGenericEvent call using the returned event id.

◆ celix_framework_setLogCallback()

CELIX_FRAMEWORK_EXPORT void celix_framework_setLogCallback ( celix_framework_t *  fw,
void *  logHandle,
void(*)(void *handle, celix_log_level_e level, const char *file, const char *function, int line, const char *format, va_list formatArgs)  logFunction 
)

Sets the log function for this framework. Default the celix framework will log to stdout/stderr.

A log function can be injected to change how the Celix framework logs. Can be reset by setting the log function to NULL.

◆ celix_framework_startBundle()

CELIX_FRAMEWORK_EXPORT bool celix_framework_startBundle ( celix_framework_t *  fw,
long  bndId 
)

Start the bundle with the provided bundle id. Will silently ignore bundle ids < 0.

Parameters
fwThe Celix framework
bndIdThe bundle id to start.
Returns
true if the bundle is found & correctly started. False if not.

◆ celix_framework_startBundleAsync()

CELIX_FRAMEWORK_EXPORT void celix_framework_startBundleAsync ( celix_framework_t *  fw,
long  bndId 
)

Start the bundle with the provided bundle id async. Will silently ignore bundle ids < 0.

The bundle will be started on a separate spawned thread.

Parameters
fwThe Celix framework
bndIdThe bundle id to start.

◆ celix_framework_stopBundle()

CELIX_FRAMEWORK_EXPORT bool celix_framework_stopBundle ( celix_framework_t *  fw,
long  bndId 
)

Stop the bundle with the provided bundle id. Will silently ignore bundle ids < 0.

Parameters
fwThe Celix framework
bndIdThe bundle id to stop.
Returns
true if the bundle is found & correctly stop. False if not.

◆ celix_framework_stopBundleAsync()

CELIX_FRAMEWORK_EXPORT void celix_framework_stopBundleAsync ( celix_framework_t *  fw,
long  bndId 
)

Stop the bundle with the provided bundle id async. Will silently ignore bundle ids < 0.

The bundle will be stopped on a separate spawned thread.

Parameters
fwThe Celix framework
bndIdThe bundle id to stop.

◆ celix_framework_uninstallBundle()

CELIX_FRAMEWORK_EXPORT bool celix_framework_uninstallBundle ( celix_framework_t *  fw,
long  bndId 
)

Uninstall the bundle with the provided bundle id. If needed the bundle will be stopped first. Will silently ignore bundle ids < 0.

Parameters
fwThe Celix framework
bndIdThe bundle id to uninstall.
Returns
true if the bundle is correctly uninstalled. False if not.

◆ celix_framework_uninstallBundleAsync()

CELIX_FRAMEWORK_EXPORT void celix_framework_uninstallBundleAsync ( celix_framework_t *  fw,
long  bndId 
)

Uninstall the bundle with the provided bundle id async. If needed the bundle will be stopped first. Will silently ignore bundle ids < 0.

The bundle will be uninstalled on a separate spawned thread.

Parameters
fwThe Celix framework
bndIdThe bundle id to uninstall.

◆ celix_framework_unloadBundle()

CELIX_FRAMEWORK_EXPORT bool celix_framework_unloadBundle ( celix_framework_t *  fw,
long  bndId 
)

Unload the bundle with the provided bundle id. If needed the bundle will be stopped first. Will silently ignore bundle ids < 0. Note that unloaded bundle is kept in bundle cache and can be reloaded with the celix_framework_installBundle function.

Parameters
fwThe Celix framework
bndIdThe bundle id to unload.
Returns
true if the bundle is correctly unloaded. False if not.

◆ celix_framework_unloadBundleAsync()

CELIX_FRAMEWORK_EXPORT void celix_framework_unloadBundleAsync ( celix_framework_t *  fw,
long  bndId 
)

Unload the bundle with the provided bundle id async. If needed the bundle will be stopped first. Will silently ignore bundle ids < 0. Note that unloaded bundle is kept in bundle cache and can be reloaded with the celix_framework_installBundle function. The bundle will be unloaded on a separate spawned thread.

Parameters
fwThe Celix framework
bndIdThe bundle id to unload.

◆ celix_framework_updateBundle()

CELIX_FRAMEWORK_EXPORT bool celix_framework_updateBundle ( celix_framework_t *  fw,
long  bndId,
const char *  updatedBundleUrl 
)

Update the bundle with the provided bundle id.

This will do the following:

  • unload the bundle with the specified bundle id;
  • reload the bundle from the specified location with the specified bundle id;
  • start the bundle, if it was previously active.

Will silently ignore bundle ids < 0.

Note if specified bundle location already exists in the bundle cache but with a different bundle id, the bundle will NOT be reloaded, and the update is cancelled.

Parameters
[in]fwThe Celix framework
[in]bndIdthe bundle id to update.
[in]updatedBundleUrlThe optional updated bundle url to the bundle zip file. If NULL, the existing bundle url from the bundle cache will be used, and the cache will only be updated if the zip file is newer.
Returns
true if the bundle is correctly updated. False if not.

◆ celix_framework_updateBundleAsync()

CELIX_FRAMEWORK_EXPORT void celix_framework_updateBundleAsync ( celix_framework_t *  fw,
long  bndId,
const char *  updatedBundleUrl 
)

Update the bundle with the provided bundle id async.

This will do the following:

  • unload the bundle with the specified bundle id;
  • reload the bundle from the specified location with the specified bundle id;
  • start the bundle, if it was previously active.

Will silently ignore bundle ids < 0.

Note if specified bundle location already exists in the bundle cache but with a different bundle id, the bundle will NOT be reinstalled, and the update is cancelled.

Parameters
[in]fwThe Celix framework
[in]bndIdthe bundle id to update.
[in]updatedBundleUrlThe optional updated bundle url to the bundle zip file. If NULL, the existing bundle url from the bundle cache will be used, and the cache will only be updated if the zip file is newer.

◆ celix_framework_useActiveBundles()

CELIX_FRAMEWORK_EXPORT size_t celix_framework_useActiveBundles ( celix_framework_t *  fw,
bool  includeFrameworkBundle,
void *  callbackHandle,
void(*)(void *handle, const celix_bundle_t *bnd)  use 
)

Use the currently active bundles. The provided callback will be called for all the currently active bundles. The bundle state is guaranteed to be active during the callback.

Warning
Calling synchronous bundle-state changing functions (e.g. celix_bundleContext_stopBundle) from the callback will lead to deadlocks.
Parameters
fwThe framework.
includeFrameworkBundleIf true the callback will also be triggered for the framework bundle.
callbackHandleThe data pointer, which will be used in the callbacks
useThe callback which will be called for the currently active bundles.
Returns
The number of times the use callback is called.

◆ celix_framework_useBundle()

CELIX_FRAMEWORK_EXPORT bool celix_framework_useBundle ( celix_framework_t *  fw,
bool  onlyActive,
long  bndId,
void *  callbackHandle,
void(*)(void *handle, const celix_bundle_t *bnd)  use 
)

Use the bundle with the provided bundle id The provided callback will be called if the bundle is found.

Warning
Calling synchronous bundle-state changing functions (e.g. celix_bundleContext_stopBundle) with onlyActive=true from the callback will lead to deadlocks. Using a bundle's context, e.g. calling celix_bundle_listServiceTrackers, with onlyActive=false from the callback is generally dangerous. However, in some cases, the target bundle's context is guaranteed to be valid, e.g. the bundle is providing a service protected by a service tracker.
Parameters
fwThe framework.
onlyActiveIf true only starting and active bundles will trigger the callback.
bundleIdThe bundle id.
callbackHandleThe data pointer, which will be used in the callbacks
useThe callback which will be called for the currently started bundles. The bundle pointers are only guaranteed to be valid during the callback.
Returns
Returns true if the bundle is found and the callback is called.

◆ celix_framework_useBundles()

CELIX_FRAMEWORK_EXPORT size_t celix_framework_useBundles ( celix_framework_t *  fw,
bool  includeFrameworkBundle,
void *  callbackHandle,
void(*)(void *handle, const celix_bundle_t *bnd)  use 
)

Use the currently installed bundles. The provided callback will be called for all the currently installed bundles.

Warning
It is dangerous to use the provided bundle's context from the callback, since it may be invalid for an inactive bundle.
Parameters
fwThe framework.
includeFrameworkBundleIf true the callback will also be triggered for the framework bundle.
callbackHandleThe data pointer, which will be used in the callbacks
useThe callback which will be called for the currently installed bundles. The bundle pointers are only guaranteed to be valid during the callback.
Returns
The number of times the use callback is called.

◆ celix_framework_waitForEmptyEventQueue()

CELIX_FRAMEWORK_EXPORT void celix_framework_waitForEmptyEventQueue ( celix_framework_t *  fw)

Wait until the framework event queue is empty.

The Celix framework has an event queue which (among others) handles various events. This function can be used to ensure that all queue events are handled.

Note scheduled events are not part of the event queue.

Parameters
fwThe Celix Framework

◆ celix_framework_waitForEmptyEventQueueFor()

CELIX_FRAMEWORK_EXPORT celix_status_t celix_framework_waitForEmptyEventQueueFor ( celix_framework_t *  fw,
double  timeoutInSeconds 
)

Wait until the framework event queue is empty or the provided period is reached.

The Celix framework has an event queue which (among others) handles various events. This function can be used to ensure that all queue events are handled.

Note scheduled events are not part of the event queue.

Parameters
[in]fwThe Celix Framework.
[in]timeoutInSecondsThe period in seconds to wait for the event queue to be empty. 0 means wait forever.
Returns
CELIX_SUCCESS if the event queue is empty or ETIMEDOUT if the timeoutInSeconds is reached.

◆ celix_framework_waitForGenericEvent()

CELIX_FRAMEWORK_EXPORT void celix_framework_waitForGenericEvent ( celix_framework_t *  fw,
long  eventId 
)

Wait until a event from the event queue with the provided event id is completely handled. This function will directly return if the provided event id is not in the event loop (already done or never issued).

Note scheduled events are not part of the event queue.

◆ celix_framework_waitForStop()

CELIX_FRAMEWORK_EXPORT void celix_framework_waitForStop ( celix_framework_t *  framework)

Wait until the framework is stopped.

◆ celix_framework_waitUntilNoEventsForBnd()

CELIX_FRAMEWORK_EXPORT void celix_framework_waitUntilNoEventsForBnd ( celix_framework_t *  fw,
long  bndId 
)

wait until all events from the event queue for the bundle identified by the bndId are processed.

If bndId < 0, wait until all bundle events (events associated with a bundle) from the event queue are processed. Note scheduled events are not part of the event queue.

◆ celix_framework_waitUntilNoPendingRegistration()

CELIX_FRAMEWORK_EXPORT void celix_framework_waitUntilNoPendingRegistration ( celix_framework_t *  fw)

wait until all pending service registration are processed.