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.
|
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"
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... | |
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:
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_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.
fw | The framework |
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.
fw | The framework |
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_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.
fw | The Celix framework |
bundleLoc | The bundle location to the bundle zip file. |
autoStart | If the bundle should also be started. |
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.
fw | The Celix framework |
bundleLoc | The bundle location to the bundle zip file. |
autoStart | If the bundle should also be started. |
CELIX_FRAMEWORK_EXPORT bool celix_framework_isBundleActive | ( | celix_framework_t * | fw, |
long | bndId | ||
) |
Check whether the bundle is active.
fw | The Celix framework |
bndId | The bundle id to check |
CELIX_FRAMEWORK_EXPORT bool celix_framework_isBundleInstalled | ( | celix_framework_t * | fw, |
long | bndId | ||
) |
Check whether a bundle is installed.
fw | The Celix framework |
bndId | The bundle id to check |
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_EXPORT bool celix_framework_isEventQueueEmpty | ( | celix_framework_t * | fw | ) |
Check if the event queue is empty.
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).
framework | The Celix framework. |
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).
framework | The Celix framework. |
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_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_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.
fw | The Celix framework |
bndId | The bundle id to start. |
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.
fw | The Celix framework |
bndId | The bundle id to start. |
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.
fw | The Celix framework |
bndId | The bundle id to stop. |
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.
fw | The Celix framework |
bndId | The bundle id to stop. |
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.
fw | The Celix framework |
bndId | The bundle id to uninstall. |
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.
fw | The Celix framework |
bndId | The bundle id to uninstall. |
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.
fw | The Celix framework |
bndId | The bundle id to unload. |
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.
fw | The Celix framework |
bndId | The bundle id to unload. |
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:
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.
[in] | fw | The Celix framework |
[in] | bndId | the bundle id to update. |
[in] | updatedBundleUrl | The 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_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:
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.
[in] | fw | The Celix framework |
[in] | bndId | the bundle id to update. |
[in] | updatedBundleUrl | The 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_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.
fw | The framework. |
includeFrameworkBundle | If true the callback will also be triggered for the framework bundle. |
callbackHandle | The data pointer, which will be used in the callbacks |
use | The callback which will be called for the currently active bundles. |
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.
fw | The framework. |
onlyActive | If true only starting and active bundles will trigger the callback. |
bundleId | The bundle id. |
callbackHandle | The data pointer, which will be used in the callbacks |
use | The callback which will be called for the currently started bundles. The bundle pointers are only guaranteed to be valid during the callback. |
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.
fw | The framework. |
includeFrameworkBundle | If true the callback will also be triggered for the framework bundle. |
callbackHandle | The data pointer, which will be used in the callbacks |
use | The callback which will be called for the currently installed bundles. The bundle pointers are only guaranteed to be valid during the callback. |
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.
fw | The Celix Framework |
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.
[in] | fw | The Celix Framework. |
[in] | timeoutInSeconds | The period in seconds to wait for the event queue to be empty. 0 means wait forever. |
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_EXPORT void celix_framework_waitForStop | ( | celix_framework_t * | framework | ) |
Wait until the framework is stopped.
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_EXPORT void celix_framework_waitUntilNoPendingRegistration | ( | celix_framework_t * | fw | ) |
wait until all pending service registration are processed.