#include "celix_bundle_context_type.h"
#include "celix_framework_export.h"
#include "celix_filter.h"
#include "celix_service_factory.h"
#include "celix_bundle_event.h"
#include "celix_log_level.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_use_options
	Service Use Options used to fine tune which services to use and which callbacks to use. 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_tracked_service_use_options
	Options for using services tracked by a service tracker. These options enable specifying callbacks to be invoked for each tracked service that matches the selection criteria. If multiple callbacks are provided, each will be called for every matching service. More...

struct	celix_tracker_guard
	Tracker guard. 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_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_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_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_tracked_service_use_options	celix_tracked_service_use_options_t
	Options for using services tracked by a service tracker. These options enable specifying callbacks to be invoked for each tracked service that matches the selection criteria. If multiple callbacks are provided, each will be called for every matching service. More...

typedef struct celix_tracker_guard	celix_tracker_guard_t
	Tracker guard. 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_DEPRECATED_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_DEPRECATED_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_DEPRECATED_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 long	celix_bundleContext_trackServicesAsync (celix_bundle_context_t ctx, const char serviceName)
	Track services with the provided serviceName. More...

CELIX_FRAMEWORK_EXPORT long	celix_bundleContext_trackServices (celix_bundle_context_t ctx, const char serviceName)
	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 bool	celix_bundleContext_useTrackedService (celix_bundle_context_t ctx, long trackerId, void callbackHandle, void(use)(void handle, void *svc))
	Use the highest-ranking service tracked by the specified tracker id by invoking the provided use callback. More...

CELIX_FRAMEWORK_EXPORT size_t	celix_bundleContext_useTrackedServices (celix_bundle_context_t ctx, long trackerId, void callbackHandle, void(use)(void handle, void *svc))
	Use the services tracked by the specified tracker id by invoking the provided use callback. More...

CELIX_FRAMEWORK_EXPORT bool	celix_bundleContext_useTrackedServiceWithOptions (celix_bundle_context_t ctx, long trackerId, const celix_tracked_service_use_options_t opts)
	Use the highest-ranking service tracked by the specified tracker id by invoking the callbacks specified in the provided options. More...

CELIX_FRAMEWORK_EXPORT size_t	celix_bundleContext_useTrackedServicesWithOptions (celix_bundle_context_t ctx, long trackerId, const celix_tracked_service_use_options_t opts)
	Use the services tracked by the specified tracker id by invoking the callbacks specified in the provided options for each matching service. More...

CELIX_FRAMEWORK_EXPORT size_t	celix_bundleContext_getTrackedServiceCount (celix_bundle_context_t *ctx, long trackerId)
	Get the number of tracked services for the provided tracker id. More...

const CELIX_FRAMEWORK_EXPORT char *	celix_bundleContext_getTrackedServiceName (celix_bundle_context_t *ctx, long trackerId)
	Get the service name of the tracked services for the provided tracker id. More...

const CELIX_FRAMEWORK_EXPORT char *	celix_bundleContext_getTrackedServiceFilter (celix_bundle_context_t *ctx, long trackerId)
	Get the service filter of the tracked services for the provided tracker id. 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, if able, for (async) creation of a tracker. More...

CELIX_FRAMEWORK_EXPORT void	celix_bundleContext_waitForAsyncStopTracker (celix_bundle_context_t *ctx, long trackerId)
	Wait, if able, 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_isValidTrackerId (celix_bundle_context_t *ctx, long trackerId)
	Returns true if the provided tracker id is a tracker id for an existing tracker for the provided bundle context. 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

Typedef Documentation

◆ celix_bundle_tracking_options_t

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.

◆ celix_scheduled_event_options_t

typedef struct celix_scheduled_event_options celix_scheduled_event_options_t

◆ celix_service_filter_options_t

typedef struct celix_service_filter_options celix_service_filter_options_t

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

◆ celix_service_registration_guard_t

typedef struct celix_service_registration_guard celix_service_registration_guard_t

Service registration guard.

◆ celix_service_registration_options_t

typedef struct celix_service_registration_options celix_service_registration_options_t

Service Registration Options when registering services to the Celix framework.

◆ celix_service_tracker_info_t

typedef struct celix_service_tracker_info celix_service_tracker_info_t

Service Tracker Info provided to the service tracker tracker callbacks.

◆ celix_service_tracking_options_t

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.

◆ celix_service_use_options_t

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.

If multiple use callbacks are set, all set callbacks will be called for every service found.

◆ celix_tracked_service_use_options_t

typedef struct celix_tracked_service_use_options celix_tracked_service_use_options_t

Options for using services tracked by a service tracker. These options enable specifying callbacks to be invoked for each tracked service that matches the selection criteria. If multiple callbacks are provided, each will be called for every matching service.

◆ celix_tracker_guard_t

typedef struct celix_tracker_guard celix_tracker_guard_t

Tracker guard.

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

ctx	The bundle context
serviceName	The 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

ctx	The bundle context
serviceName	The 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

ctx	The bundle context
opts	The 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

ctx	The bundle context
opts	The 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

ctx	The bundle context
bndId	The 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

ctx	The bundle context.
name	The name of the property.
defaultValue	The 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

framework	The framework.
name	The name of the property.
defaultValue	The 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

framework	The framework.
name	The name of the property.
defaultValue	The 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

framework	The framework.
name	The name of the property.
defaultValue	The 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_getTrackedServiceCount()

CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_getTrackedServiceCount	(	celix_bundle_context_t *	ctx,
		long	trackerId
	)

Get the number of tracked services for the provided tracker id.

Silently ignore tracker ids < 0 and invalid tracker ids.

Parameters

[in]	ctx	The bundle context.
[in]	trackerId	The tracker id.

Returns: The number of tracked services or 0 if the tracker id is unknown or < 0.

◆ celix_bundleContext_getTrackedServiceFilter()

const CELIX_FRAMEWORK_EXPORT char* celix_bundleContext_getTrackedServiceFilter	(	celix_bundle_context_t *	ctx,
		long	trackerId
	)

Get the service filter of the tracked services for the provided tracker id.

The returned filter is the combination of the service name and the filter from the provided service filter options. For example serviceName="foo" and filter="(location=middle)" will result in a filter of "(&(objectClass=foo)(location=middle))"

Silently ignore tracker ids < 0 and invalid tracker ids.

Parameters

ctx	The bundle context.
trackerId	The tracker id.

Returns: The service filter of the tracked services or NULL if the tracker id is unknown or < 0.

◆ celix_bundleContext_getTrackedServiceName()

const CELIX_FRAMEWORK_EXPORT char* celix_bundleContext_getTrackedServiceName	(	celix_bundle_context_t *	ctx,
		long	trackerId
	)

Get the service name of the tracked services for the provided tracker id.

Silently ignore tracker ids < 0 and invalid tracker ids.

Parameters

ctx	The bundle context.
trackerId	The tracker id.

Returns: The service name of the tracked services or NULL if the tracker id is unknown or < 0.

◆ 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

ctx	The bundle context
bundleUrl	The bundle location to the bundle zip file.
autoStart	If 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

ctx	The bundle context.
bndId	The 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

ctx	The bundle context.
bndId	The 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_isValidTrackerId()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_isValidTrackerId	(	celix_bundle_context_t *	ctx,
		long	trackerId
	)

Returns true if the provided tracker id is a tracker id for an existing tracker for the provided bundle context.

Parameters

ctx	The bundle context.
trackerId	The tracker id.

Returns: True if the tracker id is valid.

◆ 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

ctx	The 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

ctx	The 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

ctx	The bundle context
level	The log level to use
format	printf 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

ctx	The bundle context
svc	the service object. Normally a pointer to a service struct (i.e. a struct with function pointers)
serviceName	the service name, cannot be NULL
properties	The 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

ctx	The bundle context
svc	the service object. Normally a pointer to a service struct (i.e. a struct with function pointers)
serviceName	the service name, cannot be NULL
properties	The 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

ctx	The bundle context
factory	The pointer to the factory service.
serviceName	The required service name of the services this factory will produce.
properties	The 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

ctx	The bundle context
factory	The pointer to the factory service.
serviceName	The required service name of the services this factory will produce.
properties	The 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

ctx	The bundle context
opts	The 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

ctx	The bundle context
opts	The 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]	ctx	The bundle context.
[in]	scheduledEventId	The 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]	ctx	The bundle context.
[in]	scheduledEventId	The 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]	ctx	The bundle context.
[in]	options	The 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

<0	If 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

ctx	The bundle context
bndId	The 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

ctx	The bundle context
bndId	The 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_stopTrackerAsync 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

ctx	The bundle context.
callbackHandle	The data pointer, which will be used in the callbacks
add	The callback which will be called for started bundles.
remove	The 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

ctx	The bundle context.
callbackHandle	The data pointer, which will be used in the callbacks
add	The callback which will be called for started bundles.
remove	The 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

ctx	The bundle context.
opts	The 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

ctx	The bundle context.
opts	The pointer to the bundle tracker options.

Returns: The bundle 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
	)

Track services with the provided serviceName.

Note: If possible, use the celix_bundleContext_trackServicesAsync instead.

Parameters

ctx	The bundle context.
serviceName	The required service name to track If NULL is all service are tracked.

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
	)

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

ctx	The bundle context.
serviceName	The required service name to track If NULL is all service are tracked.

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

ctx	The bundle context.
opts	The 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

ctx	The bundle context.
opts	The 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

ctx	The bundle context.
serviceName	The 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.
callbackHandle	The callback handle which will be provided as handle in the trackerAdd and trackerRemove callback.
trackerAdd	Called 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.
trackerRemove	Called 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

ctx	The bundle context
serviceName	The 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.
callbackHandle	The callback handle which will be provided as handle in the trackerAdd and trackerRemove callback.
trackerAdd	Called 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.
trackerRemove	Called when a service tracker is removed, which tracks the provided service name
doneCallbackData	call back data argument provided to the done callback function.
doneCallback	If 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]	ctx	The bundle context.
[in]	scheduledEventId	The 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

ctx	The bundle context
bndId	The 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

ctx	The bundle context
serviceId	The 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

ctx	The bundle context
serviceId	The service id
doneData	The data used on the doneCallback (if present)
doneCallback	If 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

ctx	The bundle context
bndId	The bundle id to update.
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.

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

ctx	The bundle context.
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.

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

ctx	The bundle context.
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.

Returns: The number of times the use callback is called (nr of installed bundles).

◆ celix_bundleContext_useService()

CELIX_FRAMEWORK_DEPRECATED_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.

Warning: Cannot be called from the Celix event thread.

Deprecated:: celix_bundleContext_useService is deprecated and should be considered test utils functions. In operational code use celix_bundleContext_trackService* combined with celix_bundleContext_useTrackedService* functions instead.

The Celix framework will ensure that the targeted service cannot be removed during the callback and the callback is called on the calling thread.

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

ctx	The bundle context
serviceName	the required service name.
callbackHandle	The data pointer, which will be used in the callbacks
use	The callback, which will be called when service is retrieved.

Returns: True if a service was found and the callback was called.

◆ celix_bundleContext_useServices()

CELIX_FRAMEWORK_DEPRECATED_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.

Warning: Cannot be called from the Celix event thread.

Deprecated:: celix_bundleContext_useServices is deprecated and should be considered test utils functions. In operational code use celix_bundleContext_trackService* combined with celix_bundleContext_useTrackedService* functions instead.

The Celix framework will ensure that the targeted service cannot be removed during the callback and the callback is called on the calling thread.

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

ctx	The bundle context
serviceName	the required service name.
callbackHandle	The data pointer, which will be used in the callbacks
use	The 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.

Note: celix_bundleContext_useService should be considered test utils functions. For production code, use celix_bundleContext_trackService* combined with celix_bundleContext_useTrackedService* functions instead.

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

ctx	The bundle context.
opts	The required options. Note that the serviceName is required.

Returns: The number of services found and called

◆ celix_bundleContext_useServiceWithId()

CELIX_FRAMEWORK_DEPRECATED_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.

Warning: Cannot be called from the Celix event thread.

Deprecated:: celix_bundleContext_useServiceWithId is deprecated and should be considered test utils functions. In operational code use celix_bundleContext_trackService* combined with celix_bundleContext_useTrackedService* functions instead.

The Celix framework will ensure that the targeted service cannot be removed during the callback and the callback is called on the calling thread.

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

Parameters

ctx	The bundle context
serviceId	the service id.
serviceName	the service name of the service. Should match with the registered service name of the provided service id (sanity check)
callbackHandle	The data pointer, which will be used in the callbacks
use	The callback, which will be called when service is retrieved.
bool	returns true if a service was found and the callback was called.

◆ 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.

Note: celix_bundleContext_useService should be considered a test util function. For production code, use celix_bundleContext_trackService* combined with celix_bundleContext_useTrackedService* functions instead.

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

ctx	The bundle context.
opts	The required options. Note that the serviceName is required.

Returns: True if a service was found.

◆ celix_bundleContext_useTrackedService()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useTrackedService	(	celix_bundle_context_t *	ctx,
		long	trackerId,
		void *	callbackHandle,
		void()(void handle, void *svc)	use
	)

Use the highest-ranking service tracked by the specified tracker id by invoking the provided use callback.

The callback is executed on the thread that invokes this function, and the function waits until the use callback is completed before returning.

A tracker id less than 0 is ignored without action. An invalid (non-existent) tracker id of 0 or greater results in a logged error, and the function returns false.

Parameters

[in]	ctx	The bundle context.
[in]	trackerId	The service tracker id.
[in]	callbackHandle	An optional pointer to a user-defined context or data structure, passed to the provided use callback function.
[in]	use	The use callback invoked for highest-ranking service tracked.

Returns: True if a service was found and the provided use callback was executed; false if the tracker is not yet active (asynchronous tracker creation), the are no matching services tracked or if the tracker id is invalid.

◆ celix_bundleContext_useTrackedServices()

CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useTrackedServices	(	celix_bundle_context_t *	ctx,
		long	trackerId,
		void *	callbackHandle,
		void()(void handle, void *svc)	use
	)

Use the services tracked by the specified tracker id by invoking the provided use callback.

The callback is executed on the thread that invokes this function, and the function waits until the use callback, called for all tracked. services, is completed before returning.

A tracker id less than 0 is ignored without action. An invalid (non-existent) tracker id of 0 or greater results in a logged error, and the function returns 0.

Parameters

[in]	ctx	The bundle context.
[in]	trackerId	The service tracker id.
[in]	callbackHandle	An optional pointer to a user-defined context or data structure, passed to the provided use callback function.
[in]	use	The use callback invoked for all tracked services.

Returns: The number of services found. Returns 0 if the tracker is not yet active (asynchronous tracker creation), 0 services are found or if the tracker id is invalid.

◆ celix_bundleContext_useTrackedServicesWithOptions()

CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useTrackedServicesWithOptions	(	celix_bundle_context_t *	ctx,
		long	trackerId,
		const celix_tracked_service_use_options_t *	opts
	)

Use the services tracked by the specified tracker id by invoking the callbacks specified in the provided options for each matching service.

The callbacks are executed on the thread that invokes this function, and the function waits until all callbacks for all found services are completed before returning.

A tracker id less than 0 is ignored without action. An invalid (non-existent) tracker id of 0 or greater results in a logged error, and the function returns 0.

Parameters

[in]	ctx	The bundle context.
[in]	trackerId	The service tracker id.
[in]	opts	The service use options containing callbacks and additional configurations.

Returns: The number of services found and for which the specified callbacks were executed. Returns 0 if the tracker is not yet active (asynchronous tracker creation), 0 services are found or if the tracker id is invalid.

◆ celix_bundleContext_useTrackedServiceWithOptions()

CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useTrackedServiceWithOptions	(	celix_bundle_context_t *	ctx,
		long	trackerId,
		const celix_tracked_service_use_options_t *	opts
	)

Use the highest-ranking service tracked by the specified tracker id by invoking the callbacks specified in the provided options.

The callbacks are executed on the thread that invokes this function, and the function waits until all callbacks are completed before returning.

A tracker id less than 0 is ignored without action. An invalid (non-existent) tracker id of 0 or greater results in a logged error, and the function returns false.

Parameters

[in]	ctx	The bundle context.
[in]	trackerId	The service tracker id.
[in]	opts	The service use options containing callbacks and additional configurations.

Returns: True if a service was found and the specified callbacks were executed; false if the tracker is not yet active (asynchronous tracker creation), the are no matching services tracked or if the tracker id is invalid.

◆ 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, if able, for (async) stopping of tracking.

Will silently ignore trackerId < 0 and log an error if the tracker id is unknown. If called on the Apache Celix event loop thread, the function will log a warning and return immediately.

Parameters

[in]	ctx	The bundle context.
[in]	trackerId	The tracker id.

◆ celix_bundleContext_waitForAsyncTracker()

CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncTracker	(	celix_bundle_context_t *	ctx,
		long	trackerId
	)

Wait, if able, for (async) creation of a tracker.

Will silently ignore trackerId < 0 and log an error if the tracker id is unknown. If called on the Apache Celix event loop thread, the function will log a warning and return immediately.

Parameters

[in]	ctx	The bundle context.
[in]	trackerId	The tracker id.

◆ 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]	ctx	The bundle context.
[in]	scheduledEventId	The scheduled event id to wait for.
[in]	waitTimeInSeconds	The 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]	ctx	The bundle context.
[in]	scheduledEventId	The 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.

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ CELIX_EMPTY_SCHEDULED_EVENT_OPTIONS

◆ CELIX_OPTS_INIT

Typedef Documentation

◆ celix_bundle_tracking_options_t

◆ celix_scheduled_event_options_t

◆ celix_service_filter_options_t

◆ celix_service_registration_guard_t

◆ celix_service_registration_options_t

◆ celix_service_tracker_info_t

◆ celix_service_tracking_options_t

◆ celix_service_use_options_t

◆ celix_tracked_service_use_options_t

◆ celix_tracker_guard_t

Function Documentation

◆ celix_bundleContext_findService()

◆ celix_bundleContext_findServices()

◆ celix_bundleContext_findServicesWithOptions()

◆ celix_bundleContext_findServiceWithOptions()

◆ celix_bundleContext_getBundle()

◆ celix_bundleContext_getBundleId()

◆ celix_bundleContext_getBundleSymbolicName()

◆ celix_bundleContext_getDependencyManager()

◆ celix_bundleContext_getFramework()

◆ celix_bundleContext_getProperty()

◆ celix_bundleContext_getPropertyAsBool()

◆ celix_bundleContext_getPropertyAsDouble()

◆ celix_bundleContext_getPropertyAsLong()

◆ celix_bundleContext_getTrackedServiceCount()

◆ celix_bundleContext_getTrackedServiceFilter()

◆ celix_bundleContext_getTrackedServiceName()

◆ celix_bundleContext_installBundle()

◆ celix_bundleContext_isBundleActive()

◆ celix_bundleContext_isBundleInstalled()

◆ celix_bundleContext_isServiceRegistered()

◆ celix_bundleContext_isValidTrackerId()

◆ celix_bundleContext_listBundles()

◆ celix_bundleContext_listInstalledBundles()

◆ celix_bundleContext_log()

◆ celix_bundleContext_logTssErrors()

◆ celix_bundleContext_registerService()

◆ celix_bundleContext_registerServiceAsync()

◆ celix_bundleContext_registerServiceFactory()

◆ celix_bundleContext_registerServiceFactoryAsync()

◆ celix_bundleContext_registerServiceWithOptions()

◆ celix_bundleContext_registerServiceWithOptionsAsync()

◆ celix_bundleContext_removeScheduledEvent()

◆ celix_bundleContext_removeScheduledEventAsync()

◆ celix_bundleContext_scheduleEvent()

◆ celix_bundleContext_startBundle()

◆ celix_bundleContext_stopBundle()

◆ celix_bundleContext_stopTracker()

◆ celix_bundleContext_stopTrackerAsync()

◆ celix_bundleContext_trackBundles()

◆ celix_bundleContext_trackBundlesAsync()

◆ celix_bundleContext_trackBundlesWithOptions()

◆ celix_bundleContext_trackBundlesWithOptionsAsync()

◆ celix_bundleContext_trackServices()

◆ celix_bundleContext_trackServicesAsync()

◆ celix_bundleContext_trackServicesWithOptions()

◆ celix_bundleContext_trackServicesWithOptionsAsync()

◆ celix_bundleContext_trackServiceTrackers()

◆ celix_bundleContext_trackServiceTrackersAsync()

◆ celix_bundleContext_tryRemoveScheduledEventAsync()

◆ celix_bundleContext_uninstallBundle()

◆ celix_bundleContext_unregisterService()

◆ celix_bundleContext_unregisterServiceAsync()

◆ celix_bundleContext_updateBundle()

◆ celix_bundleContext_useBundle()

◆ celix_bundleContext_useBundles()

◆ celix_bundleContext_useService()

◆ celix_bundleContext_useServices()

◆ celix_bundleContext_useServicesWithOptions()

◆ celix_bundleContext_useServiceWithId()

◆ celix_bundleContext_useServiceWithOptions()

◆ celix_bundleContext_useTrackedService()