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.
Classes | Macros | Typedefs | Functions
celix_bundle_context.h File Reference
#include <stdarg.h>
#include "celix_cleanup.h"
#include "celix_types.h"
#include "celix_service_factory.h"
#include "celix_properties.h"
#include "celix_array_list.h"
#include "celix_filter.h"
#include "celix_bundle_event.h"
#include "celix_log_level.h"
#include "celix_framework_export.h"
Include dependency graph for celix_bundle_context.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes

struct  celix_service_registration_options
 Service Registration Options when registering services to the Celix framework. More...
 
struct  celix_service_registration_guard
 Service registration guard. More...
 
struct  celix_service_filter_options
 Service filter options which can be used to query for certain services. More...
 
struct  celix_service_tracking_options
 Service Tracker Options used to fine tune which services to track and the callback to be used for the tracked services. More...
 
struct  celix_service_use_options
 Service Use Options used to fine tune which services to use and which callbacks to use. More...
 
struct  celix_bundle_tracker_options
 The Service Bundle Tracking options can be used to fine tune the requested bundle tracker options. More...
 
struct  celix_service_tracker_info
 Service Tracker Info provided to the service tracker tracker callbacks. More...
 
struct  celix_scheduled_event_options
 Celix scheduled event options, used for creating scheduling events with the celix framework. More...
 

Macros

#define CELIX_OPTS_INIT   {}
 
#define CELIX_SERVICE_USE_DIRECT   (1)
 Call the provided callbacks from the caller thread directly if set, otherwise the callbacks will be called from the Celix event loop (most likely indirectly). Note that using blocking service in the Celix event loop is generally a bad idea, which should be avoided if possible. More...
 
#define CELIX_SERVICE_USE_SOD   (2)
 Whether "service on demand" pattern is supported when CELIX_SERVICE_USE_DIRECT is set. Note that it has no effect in indirect mode, in which case "service on demand" is supported. More...
 
#define CELIX_EMPTY_SCHEDULED_EVENT_OPTIONS   {NULL, 0.0, 0.0, NULL, NULL, NULL, NULL}
 

Typedefs

typedef struct celix_service_registration_options celix_service_registration_options_t
 Service Registration Options when registering services to the Celix framework. More...
 
typedef struct celix_service_registration_guard celix_service_registration_guard_t
 Service registration guard. More...
 
typedef struct celix_service_filter_options celix_service_filter_options_t
 Service filter options which can be used to query for certain services. More...
 
typedef struct celix_service_tracking_options celix_service_tracking_options_t
 Service Tracker Options used to fine tune which services to track and the callback to be used for the tracked services. More...
 
typedef struct celix_service_use_options celix_service_use_options_t
 Service Use Options used to fine tune which services to use and which callbacks to use. More...
 
typedef struct celix_bundle_tracker_options celix_bundle_tracking_options_t
 The Service Bundle Tracking options can be used to fine tune the requested bundle tracker options. More...
 
typedef struct celix_service_tracker_info celix_service_tracker_info_t
 Service Tracker Info provided to the service tracker tracker callbacks. More...
 
typedef struct celix_scheduled_event_options celix_scheduled_event_options_t
 

Functions

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceAsync (celix_bundle_context_t *ctx, void *svc, const char *serviceName, celix_properties_t *properties)
 Register a service to the Celix framework. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerService (celix_bundle_context_t *ctx, void *svc, const char *serviceName, celix_properties_t *properties)
 Register a service to the Celix framework. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceFactoryAsync (celix_bundle_context_t *ctx, celix_service_factory_t *factory, const char *serviceName, celix_properties_t *props)
 Register a service factory in the framework. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceFactory (celix_bundle_context_t *ctx, celix_service_factory_t *factory, const char *serviceName, celix_properties_t *props)
 Register a service factory in the framework. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceWithOptionsAsync (celix_bundle_context_t *ctx, const celix_service_registration_options_t *opts)
 Register a service to the Celix framework using the provided service registration options. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceWithOptions (celix_bundle_context_t *ctx, const celix_service_registration_options_t *opts)
 Register a service to the Celix framework using the provided service registration options. More...
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncRegistration (celix_bundle_context_t *ctx, long serviceId)
 Waits til the async service registration for the provided serviceId is done. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_isServiceRegistered (celix_bundle_context_t *ctx, long serviceId)
 Checks whether a service for the provided service id is registered in the service registry. More...
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_unregisterService (celix_bundle_context_t *ctx, long serviceId)
 Unregister the service or service factory with service id. More...
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_unregisterServiceAsync (celix_bundle_context_t *ctx, long serviceId, void *doneData, void(*doneCallback)(void *doneData))
 Unregister the service or service factory with service id. More...
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncUnregistration (celix_bundle_context_t *ctx, long serviceId)
 Waits til the async service unregistration for the provided serviceId is done. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_findService (celix_bundle_context_t *ctx, const char *serviceName)
 Finds the highest ranking service and returns the service id. More...
 
CELIX_FRAMEWORK_EXPORT celix_array_list_t * celix_bundleContext_findServices (celix_bundle_context_t *ctx, const char *serviceName)
 Finds the services with the provided service name and returns a list of the found service ids. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_findServiceWithOptions (celix_bundle_context_t *ctx, const celix_service_filter_options_t *opts)
 Finds the highest ranking service and returns the service id. More...
 
CELIX_FRAMEWORK_EXPORT celix_array_list_t * celix_bundleContext_findServicesWithOptions (celix_bundle_context_t *ctx, const celix_service_filter_options_t *opts)
 Finds the services conform the provider filter options and returns a list of the found service ids. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServiceAsync (celix_bundle_context_t *ctx, const char *serviceName, void *callbackHandle, void(*set)(void *handle, void *svc))
 Track the highest ranking service with the provided serviceName. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackService (celix_bundle_context_t *ctx, const char *serviceName, void *callbackHandle, void(*set)(void *handle, void *svc))
 Track the highest ranking service with the provided serviceName. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServicesAsync (celix_bundle_context_t *ctx, const char *serviceName, void *callbackHandle, void(*add)(void *handle, void *svc), void(*remove)(void *handle, void *svc))
 Track services with the provided serviceName. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServices (celix_bundle_context_t *ctx, const char *serviceName, void *callbackHandle, void(*add)(void *handle, void *svc), void(*remove)(void *handle, void *svc))
 Track services with the provided serviceName. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServicesWithOptionsAsync (celix_bundle_context_t *ctx, const celix_service_tracking_options_t *opts)
 Tracks services using the provided tracker options. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServicesWithOptions (celix_bundle_context_t *ctx, const celix_service_tracking_options_t *opts)
 Tracks services using the provided tracker options. More...
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_stopTrackerAsync (celix_bundle_context_t *ctx, long trackerId, void *doneCallbackData, void(*doneCallback)(void *doneCallbackData))
 Stop the tracker with the provided track id. More...
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncTracker (celix_bundle_context_t *ctx, long trackerId)
 Wait for (async) creation of tracker. More...
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncStopTracker (celix_bundle_context_t *ctx, long trackerId)
 Wait for (async) stopping of tracking. More...
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_stopTracker (celix_bundle_context_t *ctx, long trackerId)
 Stop the tracker with the provided track id. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useServiceWithId (celix_bundle_context_t *ctx, long serviceId, const char *serviceName, void *callbackHandle, void(*use)(void *handle, void *svc))
 Use the service with the provided service id using the provided callback. The Celix framework will ensure that the targeted service cannot be removed during the callback. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useService (celix_bundle_context_t *ctx, const char *serviceName, void *callbackHandle, void(*use)(void *handle, void *svc))
 Use the highest ranking service with the provided service name using the provided callback. More...
 
CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useServices (celix_bundle_context_t *ctx, const char *serviceName, void *callbackHandle, void(*use)(void *handle, void *svc))
 Use the services with the provided service name using the provided callback. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useServiceWithOptions (celix_bundle_context_t *ctx, const celix_service_use_options_t *opts)
 Use the highest ranking service satisfying the provided service filter options using the provided callback. More...
 
CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useServicesWithOptions (celix_bundle_context_t *ctx, const celix_service_use_options_t *opts)
 Use the services with the provided service filter options using the provided callback. More...
 
CELIX_FRAMEWORK_EXPORT celix_array_list_t * celix_bundleContext_listBundles (celix_bundle_context_t *ctx)
 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_bundleContext_listInstalledBundles (celix_bundle_context_t *ctx)
 List the installed bundle ids. The bundle ids does not include the framework bundle (bundle id CELIX_FRAMEWORK_BUNDLE_ID). More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_isBundleInstalled (celix_bundle_context_t *ctx, long bndId)
 Check whether a bundle is installed. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_isBundleActive (celix_bundle_context_t *ctx, long bndId)
 Check whether the bundle is active. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_installBundle (celix_bundle_context_t *ctx, const char *bundleUrl, bool autoStart)
 Install and optional start a bundle. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_uninstallBundle (celix_bundle_context_t *ctx, 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_bundleContext_stopBundle (celix_bundle_context_t *ctx, long bndId)
 Stop the bundle with the provided bundle id. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_startBundle (celix_bundle_context_t *ctx, long bndId)
 Start the bundle with the provided bundle id. Will silently ignore bundle ids < 0. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_updateBundle (celix_bundle_context_t *ctx, long bndId, const char *updatedBundleUrl)
 Update the bundle with the provided bundle id. More...
 
CELIX_FRAMEWORK_EXPORT char * celix_bundleContext_getBundleSymbolicName (celix_bundle_context_t *ctx, long bndId)
 Returns the bundle symbolic name for the provided bundle id. The caller is owner of the return string. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundlesAsync (celix_bundle_context_t *ctx, void *callbackHandle, void(*onStarted)(void *handle, const celix_bundle_t *bundle), void(*onStopped)(void *handle, const celix_bundle_t *bundle))
 Track bundles. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundles (celix_bundle_context_t *ctx, void *callbackHandle, void(*onStarted)(void *handle, const celix_bundle_t *bundle), void(*onStopped)(void *handle, const celix_bundle_t *bundle))
 Track bundles. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundlesWithOptionsAsync (celix_bundle_context_t *ctx, const celix_bundle_tracking_options_t *opts)
 Tracks bundles using the provided bundle tracker options. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundlesWithOptions (celix_bundle_context_t *ctx, const celix_bundle_tracking_options_t *opts)
 Tracks bundles using the provided bundle tracker options. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useBundle (celix_bundle_context_t *ctx, long bundleId, void *callbackHandle, void(*use)(void *handle, const celix_bundle_t *bundle))
 Use the bundle with the provided bundle id. More...
 
CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useBundles (celix_bundle_context_t *ctx, void *callbackHandle, void(*use)(void *handle, const celix_bundle_t *bundle))
 Use the currently installed bundles. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServiceTrackersAsync (celix_bundle_context_t *ctx, const char *serviceName, void *callbackHandle, void(*trackerAdd)(void *handle, const celix_service_tracker_info_t *info), void(*trackerRemove)(void *handle, const celix_service_tracker_info_t *info), void *doneCallbackData, void(*doneCallback)(void *doneCallbackData))
 Track the service tracker targeting the provided service name. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServiceTrackers (celix_bundle_context_t *ctx, const char *serviceName, void *callbackHandle, void(*trackerAdd)(void *handle, const celix_service_tracker_info_t *info), void(*trackerRemove)(void *handle, const celix_service_tracker_info_t *info))
 Track the service tracker targeting the provided service name. More...
 
CELIX_FRAMEWORK_EXPORT celix_dependency_manager_t * celix_bundleContext_getDependencyManager (celix_bundle_context_t *ctx)
 Gets the dependency manager for this bundle context. More...
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForEvents (celix_bundle_context_t *ctx)
 Wait until all Celix event for this bundle are completed. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_scheduleEvent (celix_bundle_context_t *ctx, const celix_scheduled_event_options_t *options)
 Add a scheduled event to the Celix framework. More...
 
CELIX_FRAMEWORK_EXPORT celix_status_t celix_bundleContext_wakeupScheduledEvent (celix_bundle_context_t *ctx, long scheduledEventId)
 Wakeup a scheduled event and returns immediately, not waiting for the scheduled event callback to be called. More...
 
CELIX_FRAMEWORK_EXPORT celix_status_t celix_bundleContext_waitForScheduledEvent (celix_bundle_context_t *ctx, long scheduledEventId, double waitTimeInSeconds)
 Wait until the next scheduled event is processed. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_removeScheduledEvent (celix_bundle_context_t *ctx, long scheduledEventId)
 Cancel and remove a scheduled event. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_removeScheduledEventAsync (celix_bundle_context_t *ctx, long scheduledEventId)
 Cancel and remove a scheduled event asynchronously. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_tryRemoveScheduledEventAsync (celix_bundle_context_t *ctx, long scheduledEventId)
 Try to cancel and remove a scheduled event asynchronously. More...
 
CELIX_FRAMEWORK_EXPORT celix_bundle_t * celix_bundleContext_getBundle (const celix_bundle_context_t *ctx)
 Returns the bundle for this bundle context. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_getBundleId (const celix_bundle_context_t *ctx)
 Returns the bundle if for the bundle of this bundle context. More...
 
CELIX_FRAMEWORK_EXPORT celix_framework_t * celix_bundleContext_getFramework (const celix_bundle_context_t *ctx)
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_log (const celix_bundle_context_t *ctx, celix_log_level_e level, const char *format,...) __attribute__((format(printf
 Logs a message to Celix framework logger with the provided log level. More...
 
CELIX_FRAMEWORK_EXPORT void CELIX_FRAMEWORK_EXPORT void celix_bundleContext_vlog (const celix_bundle_context_t *ctx, celix_log_level_e level, const char *format, va_list formatArgs) __attribute__((format(printf
 Logs a message to Celix framework logger with the provided log level. More...
 
CELIX_FRAMEWORK_EXPORT void CELIX_FRAMEWORK_EXPORT void CELIX_FRAMEWORK_EXPORT void celix_bundleContext_logTssErrors (const celix_bundle_context_t *ctx, celix_log_level_e level)
 Logs celix thread-specific storage error messages(celix_err) ith the provided celix log level. Silently ignores log level CELIX_LOG_LEVEL_DISABLED. More...
 
const CELIX_FRAMEWORK_EXPORT char * celix_bundleContext_getProperty (celix_bundle_context_t *ctx, const char *key, const char *defaultVal)
 Get the config property for the given key. More...
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_getPropertyAsLong (celix_bundle_context_t *ctx, const char *name, long defaultValue)
 Get the config property for the given key converted as long value. More...
 
CELIX_FRAMEWORK_EXPORT double celix_bundleContext_getPropertyAsDouble (celix_bundle_context_t *ctx, const char *name, double defaultValue)
 Get the config property for the given key converted as double value. More...
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_getPropertyAsBool (celix_bundle_context_t *ctx, const char *name, bool defaultValue)
 Get the config property for the given key converted as bool value. More...
 

Macro Definition Documentation

◆ CELIX_EMPTY_SCHEDULED_EVENT_OPTIONS

#define CELIX_EMPTY_SCHEDULED_EVENT_OPTIONS   {NULL, 0.0, 0.0, NULL, NULL, NULL, NULL}

◆ CELIX_OPTS_INIT

#define CELIX_OPTS_INIT   {}

Init macro so that the opts are correctly initialized for C++ compilers

◆ CELIX_SERVICE_USE_DIRECT

#define CELIX_SERVICE_USE_DIRECT   (1)

Call the provided callbacks from the caller thread directly if set, otherwise the callbacks will be called from the Celix event loop (most likely indirectly). Note that using blocking service in the Celix event loop is generally a bad idea, which should be avoided if possible.

◆ CELIX_SERVICE_USE_SOD

#define CELIX_SERVICE_USE_SOD   (2)

Whether "service on demand" pattern is supported when CELIX_SERVICE_USE_DIRECT is set. Note that it has no effect in indirect mode, in which case "service on demand" is supported.

Typedef Documentation

◆ celix_bundle_tracking_options_t

The Service Bundle Tracking options can be used to fine tune the requested bundle tracker options.

◆ celix_scheduled_event_options_t

◆ celix_service_filter_options_t

Service filter options which can be used to query for certain services.

◆ celix_service_registration_guard_t

Service registration guard.

◆ celix_service_registration_options_t

Service Registration Options when registering services to the Celix framework.

◆ celix_service_tracker_info_t

Service Tracker Info provided to the service tracker tracker callbacks.

◆ celix_service_tracking_options_t

Service Tracker Options used to fine tune which services to track and the callback to be used for the tracked services.

◆ celix_service_use_options_t

Service Use Options used to fine tune which services to use and which callbacks to use.

Function Documentation

◆ celix_bundleContext_findService()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_findService ( celix_bundle_context_t *  ctx,
const char *  serviceName 
)

Finds the highest ranking service and returns the service id.

Parameters
ctxThe bundle context
serviceNameThe required service name
Returns
If found a valid service id (>= 0) if not found -1.

◆ celix_bundleContext_findServices()

CELIX_FRAMEWORK_EXPORT celix_array_list_t* celix_bundleContext_findServices ( celix_bundle_context_t *  ctx,
const char *  serviceName 
)

Finds the services with the provided service name and returns a list of the found service ids.

Parameters
ctxThe bundle context
serviceNameThe required service name
Returns
A array list with as value a long int.

◆ celix_bundleContext_findServicesWithOptions()

CELIX_FRAMEWORK_EXPORT celix_array_list_t* celix_bundleContext_findServicesWithOptions ( celix_bundle_context_t *  ctx,
const celix_service_filter_options_t opts 
)

Finds the services conform the provider filter options and returns a list of the found service ids.

Parameters
ctxThe bundle context
optsThe pointer to the filter options.
Returns
A array list with as value a long int.

◆ celix_bundleContext_findServiceWithOptions()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_findServiceWithOptions ( celix_bundle_context_t *  ctx,
const celix_service_filter_options_t opts 
)

Finds the highest ranking service and returns the service id.

Parameters
ctxThe bundle context
optsThe pointer to the filter options.
Returns
If found a valid service id (>= 0) if not found -1.

◆ celix_bundleContext_getBundle()

CELIX_FRAMEWORK_EXPORT celix_bundle_t* celix_bundleContext_getBundle ( const celix_bundle_context_t *  ctx)

Returns the bundle for this bundle context.

◆ celix_bundleContext_getBundleId()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_getBundleId ( const celix_bundle_context_t *  ctx)

Returns the bundle if for the bundle of this bundle context.

◆ celix_bundleContext_getBundleSymbolicName()

CELIX_FRAMEWORK_EXPORT char* celix_bundleContext_getBundleSymbolicName ( celix_bundle_context_t *  ctx,
long  bndId 
)

Returns the bundle symbolic name for the provided bundle id. The caller is owner of the return string.

Parameters
ctxThe bundle context
bndIdThe bundle id to retrieve the symbolic name for.
Returns
The bundle symbolic name or NULL if the bundle for the provided bundle id does not exist.

◆ celix_bundleContext_getDependencyManager()

CELIX_FRAMEWORK_EXPORT celix_dependency_manager_t* celix_bundleContext_getDependencyManager ( celix_bundle_context_t *  ctx)

Gets the dependency manager for this bundle context.

Returns
the dependency manager or NULL if unsuccessful.

◆ celix_bundleContext_getFramework()

CELIX_FRAMEWORK_EXPORT celix_framework_t* celix_bundleContext_getFramework ( const celix_bundle_context_t *  ctx)

◆ celix_bundleContext_getProperty()

const CELIX_FRAMEWORK_EXPORT char* celix_bundleContext_getProperty ( celix_bundle_context_t *  ctx,
const char *  key,
const char *  defaultVal 
)

Get the config property for the given key.

The config property is a property from the framework configuration or a system property. If a system property is found, the system property is returned. Otherwise the framework configuration property - if found - is returned.

Parameters
ctxThe bundle context.
nameThe name of the property.
defaultValueThe default value if the property is not found.
Returns
The property value or the default value if the property is not found.

◆ celix_bundleContext_getPropertyAsBool()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_getPropertyAsBool ( celix_bundle_context_t *  ctx,
const char *  name,
bool  defaultValue 
)

Get the config property for the given key converted as bool value.

The config property is a property from the framework configuration or a system property. If a system property is found, the system property is returned. Otherwise the framework configuration property - if found - is returned.

Parameters
frameworkThe framework.
nameThe name of the property.
defaultValueThe default value if the property is not found.
Returns
The property value or the default value if the property is not found or the property value cannot be converted to a bool value.

◆ celix_bundleContext_getPropertyAsDouble()

CELIX_FRAMEWORK_EXPORT double celix_bundleContext_getPropertyAsDouble ( celix_bundle_context_t *  ctx,
const char *  name,
double  defaultValue 
)

Get the config property for the given key converted as double value.

The config property is a property from the framework configuration or a system property. If a system property is found, the system property is returned. Otherwise the framework configuration property - if found - is returned.

Parameters
frameworkThe framework.
nameThe name of the property.
defaultValueThe default value if the property is not found.
Returns
The property value or the default value if the property is not found or the property value cannot be converted to a double value.

◆ celix_bundleContext_getPropertyAsLong()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_getPropertyAsLong ( celix_bundle_context_t *  ctx,
const char *  name,
long  defaultValue 
)

Get the config property for the given key converted as long value.

The config property is a property from the framework configuration or a system property. If a system property is found, the system property is returned. Otherwise the framework configuration property - if found - is returned.

Parameters
frameworkThe framework.
nameThe name of the property.
defaultValueThe default value if the property is not found.
Returns
The property value or the default value if the property is not found or the property value cannot be converted to a long value.

◆ celix_bundleContext_installBundle()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_installBundle ( celix_bundle_context_t *  ctx,
const char *  bundleUrl,
bool  autoStart 
)

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

If this function is called on the Celix event thread and autoStart is true, the actual starting of the bundle will be done async and on a separate thread. If this function is called from a different thread than the Celix event thread and the autoStart is true, then the function will return after the bundle is started.

Parameters
ctxThe bundle context
bundleUrlThe 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_bundleContext_isBundleActive()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_isBundleActive ( celix_bundle_context_t *  ctx,
long  bndId 
)

Check whether the bundle is active.

Parameters
ctxThe bundle context.
bndIdThe bundle id to check
Returns
true if the bundle is installed and active.

◆ celix_bundleContext_isBundleInstalled()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_isBundleInstalled ( celix_bundle_context_t *  ctx,
long  bndId 
)

Check whether a bundle is installed.

Parameters
ctxThe bundle context.
bndIdThe bundle id to check
Returns
true if the bundle is installed.

◆ celix_bundleContext_isServiceRegistered()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_isServiceRegistered ( celix_bundle_context_t *  ctx,
long  serviceId 
)

Checks whether a service for the provided service id is registered in the service registry.

Note return false if the service for the provided service id is still pending in the event loop. Silently ignore service ids < 0 (returns false).

Returns true if the service is registered in the service registry.

◆ celix_bundleContext_listBundles()

CELIX_FRAMEWORK_EXPORT celix_array_list_t* celix_bundleContext_listBundles ( celix_bundle_context_t *  ctx)

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

Parameters
ctxThe bundle context.
Returns
A array with bundle ids (long). The caller is responsible for destroying the array.

◆ celix_bundleContext_listInstalledBundles()

CELIX_FRAMEWORK_EXPORT celix_array_list_t* celix_bundleContext_listInstalledBundles ( celix_bundle_context_t *  ctx)

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

Parameters
ctxThe bundle context.
Returns
A array with bundle ids (long). The caller is responsible for destroying the array.

◆ celix_bundleContext_log()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_log ( const celix_bundle_context_t *  ctx,
celix_log_level_e  level,
const char *  format,
  ... 
)

Logs a message to Celix framework logger with the provided log level.

Parameters
ctxThe bundle context
levelThe log level to use
formatprintf style format string
...printf style format arguments

◆ celix_bundleContext_logTssErrors()

CELIX_FRAMEWORK_EXPORT void CELIX_FRAMEWORK_EXPORT void CELIX_FRAMEWORK_EXPORT void celix_bundleContext_logTssErrors ( const celix_bundle_context_t *  ctx,
celix_log_level_e  level 
)

Logs celix thread-specific storage error messages(celix_err) ith the provided celix log level. Silently ignores log level CELIX_LOG_LEVEL_DISABLED.

◆ celix_bundleContext_registerService()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerService ( celix_bundle_context_t *  ctx,
void *  svc,
const char *  serviceName,
celix_properties_t *  properties 
)

Register a service to the Celix framework.

Note: Please use the celix_bundleContext_registerServiceAsync instead.

Parameters
ctxThe bundle context
svcthe service object. Normally a pointer to a service struct (i.e. a struct with function pointers)
serviceNamethe service name, cannot be NULL
propertiesThe meta properties associated with the service. The service registration will take ownership of the properties (i.e. no destroy needed)
Returns
The serviceId (>=0) or -1 if the registration was unsuccessful.

◆ celix_bundleContext_registerServiceAsync()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceAsync ( celix_bundle_context_t *  ctx,
void *  svc,
const char *  serviceName,
celix_properties_t *  properties 
)

Register a service to the Celix framework.

The service will be registered async on the Celix event loop thread. This means that service registration is (probably) not yet concluded when this function returns, but is added to the event loop. Use celix_bundleContext_waitForAsyncRegistration to synchronise with the actual service registration in the framework's service registry.

Parameters
ctxThe bundle context
svcthe service object. Normally a pointer to a service struct (i.e. a struct with function pointers)
serviceNamethe service name, cannot be NULL
propertiesThe meta properties associated with the service. The service registration will take ownership of the properties (i.e. no destroy needed)
Returns
The serviceId (>=0) or -1 if the registration was unsuccessful.

◆ celix_bundleContext_registerServiceFactory()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceFactory ( celix_bundle_context_t *  ctx,
celix_service_factory_t *  factory,
const char *  serviceName,
celix_properties_t *  props 
)

Register a service factory in the framework.

The service factory will be called for every bundle requesting/de-requesting a service. This gives the provider the option to create bundle specific service instances. Note: Please use the celix_bundleContext_registerServiceFactoryAsync instead.

When a service is requested for a bundle the getService of the factory service will be called. This function must return a valid pointer to a service conform the registered service name or NULL. When a service in no longer needed for a bundle (e.g. ending the useService(s) calls or when a service tracker is stopped) the ungetService function of the service factory will be called.

Parameters
ctxThe bundle context
factoryThe pointer to the factory service.
serviceNameThe required service name of the services this factory will produce.
propertiesThe optional service factory properties. For a service consumer this will be seen as the service properties.
Returns
The serviceId (>= 0) or < 0 if the registration was unsuccessful.

◆ celix_bundleContext_registerServiceFactoryAsync()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceFactoryAsync ( celix_bundle_context_t *  ctx,
celix_service_factory_t *  factory,
const char *  serviceName,
celix_properties_t *  props 
)

Register a service factory in the framework.

The service factory will be called for every bundle requesting/de-requesting a service. This gives the provider the option to create bundle specific service instances.

When a service is requested for a bundle the getService of the factory service will be called. This function must return a valid pointer to a service conform the registered service name or NULL. When a service in no longer needed for a bundle (e.g. ending the useService(s) calls or when a service tracker is stopped) the ungetService function of the service factory will be called.

The service will be registered async on the Celix event loop thread. This means that service registration is (probably) not yet concluded when this function returns, but is added to the event loop. Use celix_bundleContext_waitForAsyncRegistration to synchronise with the actual service registration in the framework's service registry.

Parameters
ctxThe bundle context
factoryThe pointer to the factory service.
serviceNameThe required service name of the services this factory will produce.
propertiesThe optional service factory properties. For a service consumer this will be seen as the service properties.
Returns
The serviceId (>= 0) or < 0 if the registration was unsuccessful.

◆ celix_bundleContext_registerServiceWithOptions()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceWithOptions ( celix_bundle_context_t *  ctx,
const celix_service_registration_options_t opts 
)

Register a service to the Celix framework using the provided service registration options.

Note: Please use the celix_bundleContext_registerServiceAsyncWithOptions instead.

Parameters
ctxThe bundle context
optsThe pointer to the registration options. The options are only in the during registration call.
Returns
The serviceId (>= 0) or -1 if the registration was unsuccessful and -2 if the registration was cancelled (
See also
celix_bundleContext_reserveSvcId).

◆ celix_bundleContext_registerServiceWithOptionsAsync()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceWithOptionsAsync ( celix_bundle_context_t *  ctx,
const celix_service_registration_options_t opts 
)

Register a service to the Celix framework using the provided service registration options.

The service will be registered async on the Celix event loop thread. This means that service registration is (probably) not yet concluded when this function returns, but is added to the event loop.. Use celix_bundleContext_waitForAsyncRegistration to synchronise with the actual service registration in the framework's service registry.

Parameters
ctxThe bundle context
optsThe pointer to the registration options. The options are only in the during registration call.
Returns
The serviceId (>= 0) or -1 if the registration was unsuccessful and -2 if the registration was cancelled (
See also
celix_bundleContext_reserveSvcId).

◆ celix_bundleContext_removeScheduledEvent()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_removeScheduledEvent ( celix_bundle_context_t *  ctx,
long  scheduledEventId 
)

Cancel and remove a scheduled event.

Silently ignored if the scheduled event ids < 0.

This function will block until a possible in-progress scheduled event callback is finished, the scheduled event is removed and, if configured, the remove callback is called.

Parameters
[in]ctxThe bundle context.
[in]scheduledEventIdThe scheduled event id to cancel and remove.
Returns
true if a scheduled event is cancelled, false if the scheduled event id is not known.

◆ celix_bundleContext_removeScheduledEventAsync()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_removeScheduledEventAsync ( celix_bundle_context_t *  ctx,
long  scheduledEventId 
)

Cancel and remove a scheduled event asynchronously.

When this function returns, no new scheduled event callbacks will be called, but it is not guaranteed that there is still a scheduled event callback in progress and that the remove callback is called.

Silently ignored if the scheduled event ids < 0.

Parameters
[in]ctxThe bundle context.
[in]scheduledEventIdThe scheduled event id to cancel and remove.
Returns
true if a scheduled event is cancelled, false if the scheduled event id is not known.

◆ celix_bundleContext_scheduleEvent()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_scheduleEvent ( celix_bundle_context_t *  ctx,
const celix_scheduled_event_options_t options 
)

Add a scheduled event to the Celix framework.

The scheduled event will be called on the Celix framework event thread, repeatedly using the provided interval or once if only a initial delay is provided. The event callback should be relatively fast and the scheduled event interval should be relatively long, otherwise the framework event queue will be blocked and framework will not function properly.

Scheduled events can be scheduled later than the provided initial delay and interval, because they are processed after other events in the Celix event thread. The target - but not guaranteed - precision of the scheduled event trigger is 1 microsecond.

If the provided interval is 0, the scheduled event will a one-shot scheduled event and will be called once after the provided initial delay. If a bundle stops before the one-shot scheduled event is called, the scheduled event will be removed and not called.

Scheduled events should be removed by the caller when not needed anymore, except for one-shot scheduled events. one-shot are automatically removed after the event callback is called.

Note during bundle stop the framework will check if all scheduled events for the bundle are removed. For every not removed scheduled event that is not a one-shot event, a warning will be logged and the scheduled event will be removed.

Parameters
[in]ctxThe bundle context.
[in]optionsThe scheduled event options, which describe the to be added scheduled event.
Returns
The scheduled event id of the scheduled event. Can be used to cancel the event.
Return values
<0If the event could not be added.

◆ celix_bundleContext_startBundle()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_startBundle ( celix_bundle_context_t *  ctx,
long  bndId 
)

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

If this function is called on the Celix event thread, the actual starting of the bundle will be done async and on a separate thread. If this function is called from a different thread than the Celix event thread, then the function will return after the bundle is started.

Parameters
ctxThe bundle context
bndIdThe bundle id to start.
Returns
true if the bundle is found & correctly started. False if not.

◆ celix_bundleContext_stopBundle()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_stopBundle ( celix_bundle_context_t *  ctx,
long  bndId 
)

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

If this function is called on the Celix event thread, the actual stopping of the bundle will be done async and on a separate thread. If this function is called from a different thread than the Celix event thread, then the function will return after the bundle is stopped.

Parameters
ctxThe bundle context
bndIdThe bundle id to stop.
Returns
true if the bundle is found & correctly stop. False if not.

◆ celix_bundleContext_stopTracker()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_stopTracker ( celix_bundle_context_t *  ctx,
long  trackerId 
)

Stop the tracker with the provided track id.

Could be a service tracker, bundle tracker or service tracker tracker. Only works for the trackers owned by the bundle of the bundle context. Note: Please use the celix_bundleContext_registerServiceFactoryAsync instead.

Will log a error if the provided tracker id is unknown. Will silently ignore trackerId < 0.

◆ celix_bundleContext_stopTrackerAsync()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_stopTrackerAsync ( celix_bundle_context_t *  ctx,
long  trackerId,
void *  doneCallbackData,
void(*)(void *doneCallbackData)  doneCallback 
)

Stop the tracker with the provided track id.

Could be a service tracker, bundle tracker or service tracker tracker. Only works for the trackers owned by the bundle of the bundle context.

The service tracker will be destroyed async on the Celix event loop thread. This means that the function can return before the tracker is destroyed.

if the doneCallback is not NULL, this will be called when the destruction of the service tracker is done. (will be called on the event loop thread).

Will log a error if the provided tracker id is unknown. Will silently ignore trackerId < 0.

◆ celix_bundleContext_trackBundles()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundles ( celix_bundle_context_t *  ctx,
void *  callbackHandle,
void(*)(void *handle, const celix_bundle_t *bundle)  onStarted,
void(*)(void *handle, const celix_bundle_t *bundle)  onStopped 
)

Track bundles.

The add bundle callback will also be called for already installed bundles.

Note: please use celix_bundleContext_trackBundlesAsync instead.

Parameters
ctxThe bundle context.
callbackHandleThe data pointer, which will be used in the callbacks
addThe callback which will be called for started bundles.
removeThe callback which will be called when bundles are stopped.
Returns
The bundle tracker id or < 0 if unsuccessful.

◆ celix_bundleContext_trackBundlesAsync()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundlesAsync ( celix_bundle_context_t *  ctx,
void *  callbackHandle,
void(*)(void *handle, const celix_bundle_t *bundle)  onStarted,
void(*)(void *handle, const celix_bundle_t *bundle)  onStopped 
)

Track bundles.

The add bundle callback will also be called for already installed bundles.

The bundle tracker will be created async on the Celix event loop thread. This means that the function can return before the tracker is created.

Parameters
ctxThe bundle context.
callbackHandleThe data pointer, which will be used in the callbacks
addThe callback which will be called for started bundles.
removeThe callback which will be called when bundles are stopped.
Returns
The bundle tracker id or < 0 if unsuccessful.

◆ celix_bundleContext_trackBundlesWithOptions()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundlesWithOptions ( celix_bundle_context_t *  ctx,
const celix_bundle_tracking_options_t opts 
)

Tracks bundles using the provided bundle tracker options.

The tracker options are only using during this call and can safely be freed/reused after this call returns. (i.e. can be on the stack)

Note: please use celix_bundleContext_trackBundlesWithOptionsAsync instead;

Parameters
ctxThe bundle context.
optsThe pointer to the bundle tracker options.
Returns
The bundle tracker id (>=0) or < 0 if unsuccessful.

◆ celix_bundleContext_trackBundlesWithOptionsAsync()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundlesWithOptionsAsync ( celix_bundle_context_t *  ctx,
const celix_bundle_tracking_options_t opts 
)

Tracks bundles using the provided bundle tracker options.

The tracker options are only using during this call and can safely be freed/reused after this call returns. (i.e. can be on the stack)

The bundle tracker will be created async on the Celix event loop thread. This means that the function can return before the tracker is created.

Parameters
ctxThe bundle context.
optsThe pointer to the bundle tracker options.
Returns
The bundle tracker id (>=0) or < 0 if unsuccessful.

◆ celix_bundleContext_trackService()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackService ( celix_bundle_context_t *  ctx,
const char *  serviceName,
void *  callbackHandle,
void(*)(void *handle, void *svc)  set 
)

Track the highest ranking service with the provided serviceName.

The highest ranking services will used for the callback. If a new and higher ranking services the callback with be called again with the new service. If a service is removed a the callback with be called with next highest ranking service or NULL as service. Note: Please use the celix_bundleContext_trackServiceAsync instead.

Parameters
ctxThe bundle context.
serviceNameThe required service name to track. If NULL is all service are tracked.
callbackHandleThe data pointer, which will be used in the callbacks
setis a required callback, which will be called when a new highest ranking service is set.
Returns
the tracker id (>=0) or < 0 if unsuccessful.

◆ celix_bundleContext_trackServiceAsync()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServiceAsync ( celix_bundle_context_t *  ctx,
const char *  serviceName,
void *  callbackHandle,
void(*)(void *handle, void *svc)  set 
)

Track the highest ranking service with the provided serviceName.

The highest ranking services will used for the callback. If a new and higher ranking services the callback with be called again with the new service. If a service is removed a the callback with be called with next highest ranking service or NULL as service.

The service tracker will be created async on the Celix event loop thread. This means that the function can return before the tracker is created.

Parameters
ctxThe bundle context.
serviceNameThe required service name to track. If NULL is all service are tracked.
callbackHandleThe data pointer, which will be used in the callbacks
setis a required callback, which will be called when a new highest ranking service is set.
Returns
the tracker id (>=0) or < 0 if unsuccessful.

◆ celix_bundleContext_trackServices()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServices ( celix_bundle_context_t *  ctx,
const char *  serviceName,
void *  callbackHandle,
void(*)(void *handle, void *svc)  add,
void(*)(void *handle, void *svc)  remove 
)

Track services with the provided serviceName.

Note: Please use the celix_bundleContext_trackServicesAsync instead.

Parameters
ctxThe bundle context.
serviceNameThe required service name to track If NULL is all service are tracked.
callbackHandleThe data pointer, which will be used in the callbacks
addis a required callback, which will be called when a service is added and initially for the existing service.
removeis a required callback, which will be called when a service is removed
Returns
the tracker id (>=0) or < 0 if unsuccessful.

◆ celix_bundleContext_trackServicesAsync()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServicesAsync ( celix_bundle_context_t *  ctx,
const char *  serviceName,
void *  callbackHandle,
void(*)(void *handle, void *svc)  add,
void(*)(void *handle, void *svc)  remove 
)

Track services with the provided serviceName.

The service tracker will be created async on the Celix event loop thread. This means that the function can return before the tracker is created.

Parameters
ctxThe bundle context.
serviceNameThe required service name to track If NULL is all service are tracked.
callbackHandleThe data pointer, which will be used in the callbacks
addis a required callback, which will be called when a service is added and initially for the existing service.
removeis a required callback, which will be called when a service is removed
Returns
the tracker id (>=0) or < 0 if unsuccessful.

◆ celix_bundleContext_trackServicesWithOptions()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServicesWithOptions ( celix_bundle_context_t *  ctx,
const celix_service_tracking_options_t opts 
)

Tracks services using the provided tracker options.

The tracker options are only using during this call and can safely be freed/reused after this call returns. Note: Please use the celix_bundleContext_registerServiceFactoryAsync instead.

Parameters
ctxThe bundle context.
optsThe pointer to the tracker options.
Returns
the tracker id (>=0) or < 0 if unsuccessful.

◆ celix_bundleContext_trackServicesWithOptionsAsync()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServicesWithOptionsAsync ( celix_bundle_context_t *  ctx,
const celix_service_tracking_options_t opts 
)

Tracks services using the provided tracker options.

The tracker options are only using during this call and can safely be freed/reused after this call returns.

The service tracker will be created async on the Celix event loop thread. This means that the function can return before the tracker is created.

Parameters
ctxThe bundle context.
optsThe pointer to the tracker options.
Returns
the tracker id (>=0) or < 0 if unsuccessful.

◆ celix_bundleContext_trackServiceTrackers()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServiceTrackers ( celix_bundle_context_t *  ctx,
const char *  serviceName,
void *  callbackHandle,
void(*)(void *handle, const celix_service_tracker_info_t *info)  trackerAdd,
void(*)(void *handle, const celix_service_tracker_info_t *info)  trackerRemove 
)

Track the service tracker targeting the provided service name.

This can be used to track if there is an interest in a certain service and ad-hoc act on that interest.

Note that the celix_service_tracker_info_t pointer in the trackerAdd/trackerRemove callbacks are only valid during the callback.

Note: Please use celix_bundleContext_trackServiceTrackersAsync instead.

This tracker can be stopped with the celix_bundleContext_stopTracker function.

Parameters
ctxThe bundle context.
serviceNameThe target service name for the service tracker to track. If NULL is provided, add/remove callbacks will be called for all service trackers in the framework.
callbackHandleThe callback handle which will be provided as handle in the trackerAdd and trackerRemove callback.
trackerAddCalled when a service tracker is added, which tracks the provided service name. Will also be called for all existing service tracker when this tracker is started.
trackerRemoveCalled when a service tracker is removed, which tracks the provided service name
Returns
The tracker id or <0 if something went wrong (will log an error).

◆ celix_bundleContext_trackServiceTrackersAsync()

CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServiceTrackersAsync ( celix_bundle_context_t *  ctx,
const char *  serviceName,
void *  callbackHandle,
void(*)(void *handle, const celix_service_tracker_info_t *info)  trackerAdd,
void(*)(void *handle, const celix_service_tracker_info_t *info)  trackerRemove,
void *  doneCallbackData,
void(*)(void *doneCallbackData)  doneCallback 
)

Track the service tracker targeting the provided service name.

This can be used to track if there is an interest in a certain service and ad-hoc act on that interest.

Note that the celix_service_tracker_info_t pointer in the trackerAdd/trackerRemove callbacks are only valid during the callback.

This tracker can be stopped with the celix_bundleContext_stopTracker function.

The service tracker tracker will be created async on the Celix event loop thread. This means that the function can return before the tracker is created.

Parameters
ctxThe bundle context
serviceNameThe target service name for the service tracker to track. If NULL is provided, add/remove callbacks will be called for all service trackers in the framework.
callbackHandleThe callback handle which will be provided as handle in the trackerAdd and trackerRemove callback.
trackerAddCalled when a service tracker is added, which tracks the provided service name. Will also be called for all existing service tracker when this tracker is started.
trackerRemoveCalled when a service tracker is removed, which tracks the provided service name
doneCallbackDatacall back data argument provided to the done callback function.
doneCallbackIf not NULL will be called when the service tracker tracker is created. If a asyns track service is combined with a sync stop tracker, it can happen that "stop tracker" happens before the "create tracker" event is processed. In this case the doneCallback will not be called.
Returns
The tracker id or <0 if something went wrong (will log an error).

◆ celix_bundleContext_tryRemoveScheduledEventAsync()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_tryRemoveScheduledEventAsync ( celix_bundle_context_t *  ctx,
long  scheduledEventId 
)

Try to cancel and remove a scheduled event asynchronously.

Silently ignored if the scheduled event ids < 0.

When this function returns, no new scheduled event callbacks will be called, but it is not guaranteed that there is still a scheduled event callback in progress and that the remove callback is called. Will not log an error if the scheduled event id is not known.

Parameters
[in]ctxThe bundle context.
[in]scheduledEventIdThe scheduled event id to cancel.
Returns
true if a scheduled event is cancelled, false if the scheduled event id is not known.

◆ celix_bundleContext_uninstallBundle()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_uninstallBundle ( celix_bundle_context_t *  ctx,
long  bndId 
)

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

If this function is called on the Celix event thread, the actual stopping of the bundle will be done async and on a separate thread. If this function is called from a different thread than the Celix event thread, then the function will return after the bundle is stopped.

Parameters
ctxThe bundle context
bndIdThe bundle id to uninstall.
Returns
true if the bundle is correctly uninstalled. False if not.

◆ celix_bundleContext_unregisterService()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_unregisterService ( celix_bundle_context_t *  ctx,
long  serviceId 
)

Unregister the service or service factory with service id.

The service will only be unregistered if the bundle of the bundle context is the owner of the service.

Will log an error if service id is unknown. Will silently ignore services ids < 0.

Parameters
ctxThe bundle context
serviceIdThe service id

◆ celix_bundleContext_unregisterServiceAsync()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_unregisterServiceAsync ( celix_bundle_context_t *  ctx,
long  serviceId,
void *  doneData,
void(*)(void *doneData)  doneCallback 
)

Unregister the service or service factory with service id.

The service will only be unregistered if the bundle of the bundle context is the owner of the service.

The service will be umregistered async on the Celix event loop thread. This means that service unregistration is (probably) not yet concluded when this function returns. Use celix_bundleContext_waitForAsyncUnregistration to synchronise with the actual service unregistration in the framework's service registry.

Parameters
ctxThe bundle context
serviceIdThe service id
doneDataThe data used on the doneCallback (if present)
doneCallbackIf not NULL, this callback will be called when the unregisration is done. (will be called on the event loop thread)

◆ celix_bundleContext_updateBundle()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_updateBundle ( celix_bundle_context_t *  ctx,
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 reinstalled, and the update is cancelled.

If this function is called on the Celix event thread, the actual updating of the bundle will be done async and on a separate thread. If this function is called from a different thread than the Celix event thread, then the function will return after the bundle update is completed.

Parameters
ctxThe bundle context
bndIdThe bundle id to update.
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 found & correctly started. False if not.

◆ celix_bundleContext_useBundle()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useBundle ( celix_bundle_context_t *  ctx,
long  bundleId,
void *  callbackHandle,
void(*)(void *handle, const celix_bundle_t *bundle)  use 
)

Use the bundle with the provided bundle id.

The provided callback will be called if the bundle is found (installed). Call with CELIX_FRAMEWORK_BUNDLE_ID as bundleId to use the framework bundle.

Parameters
ctxThe bundle context.
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_bundleContext_useBundles()

CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useBundles ( celix_bundle_context_t *  ctx,
void *  callbackHandle,
void(*)(void *handle, const celix_bundle_t *bundle)  use 
)

Use the currently installed bundles.

The provided callback will be called for all the currently installed bundles, expect the framework bundle.

Parameters
ctxThe bundle context.
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
The number of times the use callback is called (nr of installed bundles).

◆ celix_bundleContext_useService()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useService ( celix_bundle_context_t *  ctx,
const char *  serviceName,
void *  callbackHandle,
void(*)(void *handle, void *svc)  use 
)

Use the highest ranking service with the provided service name using the provided callback.

The Celix framework will ensure that the targeted service cannot be removed during the callback.

The svc is should only be considered valid during the callback. If no service is found, the callback will not be invoked and this function will return false immediately.

This function will block until the callback is finished. As result it is possible to provide callback data from the stack.

Parameters
ctxThe bundle context
serviceNamethe required service name.
callbackHandleThe data pointer, which will be used in the callbacks
useThe callback, which will be called when service is retrieved.
Returns
True if a service was found.

◆ celix_bundleContext_useServices()

CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useServices ( celix_bundle_context_t *  ctx,
const char *  serviceName,
void *  callbackHandle,
void(*)(void *handle, void *svc)  use 
)

Use the services with the provided service name using the provided callback.

The Celix framework will ensure that the targeted service cannot be removed during the callback.

The svc is should only be considered valid during the callback. If no service is found, the callback will not be invoked and this function will return 0 immediately.

This function will block until the callback is finished. As result it is possible to provide callback data from the stack.

Parameters
ctxThe bundle context
serviceNamethe required service name.
callbackHandleThe data pointer, which will be used in the callbacks
useThe callback, which will be called for every service found.
Returns
The number of services found and called

◆ celix_bundleContext_useServicesWithOptions()

CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useServicesWithOptions ( celix_bundle_context_t *  ctx,
const celix_service_use_options_t opts 
)

Use the services with the provided service filter options using the provided callback.

The Celix framework will ensure that the targeted service cannot be removed during the callback.

The svc is should only be considered valid during the callback. If no service is found, the callback will not be invoked and this function will return 0 immediately. Note that waitTimeoutInSeconds in opts has no effect.

This function will block until the callback is finished. As result it is possible to provide callback data from the stack.

Parameters
ctxThe bundle context.
optsThe required options. Note that the serviceName is required.
Returns
The number of services found and called

◆ celix_bundleContext_useServiceWithId()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useServiceWithId ( celix_bundle_context_t *  ctx,
long  serviceId,
const char *  serviceName,
void *  callbackHandle,
void(*)(void *handle, void *svc)  use 
)

Use the service with the provided service id using the provided callback. The Celix framework will ensure that the targeted service cannot be removed during the callback.

The svc is should only be considered valid during the callback. If no service is found, the callback will not be invoked and this function will return false immediately.

This function will block until the callback is finished. As result it is possible to provide callback data from the stack.

Parameters
ctxThe bundle context
serviceIdthe service id.
serviceNamethe service name of the service. Should match with the registered service name of the provided service id (sanity check)
callbackHandleThe data pointer, which will be used in the callbacks
useThe callback, which will be called when service is retrieved.
boolreturns true if a service was found.

◆ celix_bundleContext_useServiceWithOptions()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useServiceWithOptions ( celix_bundle_context_t *  ctx,
const celix_service_use_options_t opts 
)

Use the highest ranking service satisfying the provided service filter options using the provided callback.

The Celix framework will ensure that the targeted service cannot be removed during the callback.

The svc is should only be considered valid during the callback. If no service is found the callback will not be invoked. In such cases, if a non-zero waitTimeoutInSeconds is specified in opts, this function will block until the timeout is expired or when at least one service is found, otherwise it will return false immediately.

This function will block until the callback is finished. As result it is possible to provide callback data from the stack.

Parameters
ctxThe bundle context.
optsThe required options. Note that the serviceName is required.
Returns
True if a service was found.

◆ celix_bundleContext_vlog()

CELIX_FRAMEWORK_EXPORT void CELIX_FRAMEWORK_EXPORT void celix_bundleContext_vlog ( const celix_bundle_context_t *  ctx,
celix_log_level_e  level,
const char *  format,
va_list  formatArgs 
)

Logs a message to Celix framework logger with the provided log level.

◆ celix_bundleContext_waitForAsyncRegistration()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncRegistration ( celix_bundle_context_t *  ctx,
long  serviceId 
)

Waits til the async service registration for the provided serviceId is done.

Silently ignore service ids < 0. Will directly return if there is no pending service registration for the provided service id.

◆ celix_bundleContext_waitForAsyncStopTracker()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncStopTracker ( celix_bundle_context_t *  ctx,
long  trackerId 
)

Wait for (async) stopping of tracking.

◆ celix_bundleContext_waitForAsyncTracker()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncTracker ( celix_bundle_context_t *  ctx,
long  trackerId 
)

Wait for (async) creation of tracker.

◆ celix_bundleContext_waitForAsyncUnregistration()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncUnregistration ( celix_bundle_context_t *  ctx,
long  serviceId 
)

Waits til the async service unregistration for the provided serviceId is done.

Silently ignore service < 0.

◆ celix_bundleContext_waitForEvents()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForEvents ( celix_bundle_context_t *  ctx)

Wait until all Celix event for this bundle are completed.

◆ celix_bundleContext_waitForScheduledEvent()

CELIX_FRAMEWORK_EXPORT celix_status_t celix_bundleContext_waitForScheduledEvent ( celix_bundle_context_t *  ctx,
long  scheduledEventId,
double  waitTimeInSeconds 
)

Wait until the next scheduled event is processed.

Silently ignored if the scheduled event ids < 0.

Parameters
[in]ctxThe bundle context.
[in]scheduledEventIdThe scheduled event id to wait for.
[in]waitTimeInSecondsThe maximum time to wait for the next scheduled event. If <= 0 the function will return immediately.
Returns
CELIX_SUCCESS if the scheduled event is woken up, CELIX_ILLEGAL_ARGUMENT if the scheduled event id is not known and ETIMEDOUT if the waitTimeInSeconds is reached.

◆ celix_bundleContext_wakeupScheduledEvent()

CELIX_FRAMEWORK_EXPORT celix_status_t celix_bundleContext_wakeupScheduledEvent ( celix_bundle_context_t *  ctx,
long  scheduledEventId 
)

Wakeup a scheduled event and returns immediately, not waiting for the scheduled event callback to be called.

Silently ignored if the scheduled event ids < 0.

Parameters
[in]ctxThe bundle context.
[in]scheduledEventIdThe scheduled event id to wakeup.
Returns
CELIX_SUCCESS if the scheduled event is woken up, CELIX_ILLEGAL_ARGUMENT if the scheduled event id is not known.