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

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.

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_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_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_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

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_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

ctx	The bundle context.
serviceName	The required service name to track. If NULL is all service are tracked.
callbackHandle	The data pointer, which will be used in the callbacks
set	is 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

ctx	The bundle context.
serviceName	The required service name to track. If NULL is all service are tracked.
callbackHandle	The data pointer, which will be used in the callbacks
set	is 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

ctx	The bundle context.
serviceName	The required service name to track If NULL is all service are tracked.
callbackHandle	The data pointer, which will be used in the callbacks
add	is a required callback, which will be called when a service is added and initially for the existing service.
remove	is 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

ctx	The bundle context.
serviceName	The required service name to track If NULL is all service are tracked.
callbackHandle	The data pointer, which will be used in the callbacks
add	is a required callback, which will be called when a service is added and initially for the existing service.
remove	is 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

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_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

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.

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

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.

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_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

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.

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

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