#include "celix_types.h"
#include "celix_service_factory.h"
#include "celix_properties.h"
#include "celix_array_list.h"
#include "celix_filter.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

struct	celix_service_filter_options

struct	celix_service_tracking_options

struct	celix_service_use_options

struct	celix_bundle_tracker_options

struct	celix_service_tracker_info

Macros
#define	OPTS_INIT

#define	CELIX_EMPTY_SERVICE_REGISTRATION_OPTIONS

#define	CELIX_EMPTY_SERVICE_FILTER_OPTIONS {.serviceName = NULL, .versionRange = NULL, .filter = NULL, .serviceLanguage = NULL, .ignoreServiceLanguage = false}

#define	CELIX_EMPTY_SERVICE_TRACKING_OPTIONS

#define	CELIX_EMPTY_SERVICE_USE_OPTIONS

#define	CELIX_EMPTY_BUNDLE_TRACKING_OPTIONS {.callbackHandle = NULL, .onStarted = NULL, .onStopped = NULL, .onBundleEvent = NULL}

Typedefs
typedef struct celix_service_registration_options	celix_service_registration_options_t

typedef struct celix_service_filter_options	celix_service_filter_options_t

typedef struct celix_service_tracking_options	celix_service_tracking_options_t

typedef struct celix_service_use_options	celix_service_use_options_t

typedef struct celix_bundle_tracker_options	celix_bundle_tracking_options_t

typedef struct celix_service_tracker_info	celix_service_tracker_info_t

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

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

long	celix_bundleContext_registerServiceWithOptions (celix_bundle_context_t ctx, const celix_service_registration_options_t opts)

void	celix_bundleContext_unregisterService (celix_bundle_context_t *ctx, long serviceId)

long	celix_bundleContext_findService (celix_bundle_context_t ctx, const char serviceName)

celix_array_list_t *	celix_bundleContext_findServices (celix_bundle_context_t ctx, const char serviceName)

long	celix_bundleContext_findServiceWithOptions (celix_bundle_context_t ctx, const celix_service_filter_options_t opts)

celix_array_list_t *	celix_bundleContext_findServicesWithOptions (celix_bundle_context_t ctx, const celix_service_filter_options_t opts)

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

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

long	celix_bundleContext_trackServicesWithOptions (celix_bundle_context_t ctx, const celix_service_tracking_options_t opts)

void	celix_bundleContext_stopTracker (celix_bundle_context_t *ctx, long trackerId)

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

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

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

bool	celix_bundleContext_useServiceWithOptions (celix_bundle_context_t ctx, const celix_service_use_options_t opts)

void	celix_bundleContext_useServicesWithOptions (celix_bundle_context_t ctx, const celix_service_use_options_t opts)

celix_array_list_t *	celix_bundleContext_listBundles (celix_bundle_context_t *ctx)

bool	celix_bundleContext_isBundleInstalled (celix_bundle_context_t *ctx, long bndId)

long	celix_bundleContext_installBundle (celix_bundle_context_t ctx, const char bundleLoc, bool autoStart)

bool	celix_bundleContext_uninstallBundle (celix_bundle_context_t *ctx, long bundleId)

bool	celix_bundleContext_stopBundle (celix_bundle_context_t *ctx, long bundleId)

bool	celix_bundleContext_startBundle (celix_bundle_context_t *ctx, long bundleId)

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

long	celix_bundleContext_trackBundlesWithOptions (celix_bundle_context_t ctx, const celix_bundle_tracking_options_t opts)

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

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

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

celix_dependency_manager_t *	celix_bundleContext_getDependencyManager (celix_bundle_context_t *ctx)

celix_bundle_t *	celix_bundleContext_getBundle (celix_bundle_context_t *ctx)

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

long	celix_bundleContext_getPropertyAsLong (celix_bundle_context_t ctx, const char key, long defaultValue)

double	celix_bundleContext_getPropertyAsDouble (celix_bundle_context_t ctx, const char key, double defaultValue)

bool	celix_bundleContext_getPropertyAsBool (celix_bundle_context_t ctx, const char key, bool defaultValue)

Macro Definition Documentation

#define CELIX_EMPTY_BUNDLE_TRACKING_OPTIONS {.callbackHandle = NULL, .onStarted = NULL, .onStopped = NULL, .onBundleEvent = NULL}

C Macro to create a empty celix_service_filter_options_t type.

#define CELIX_EMPTY_SERVICE_FILTER_OPTIONS {.serviceName = NULL, .versionRange = NULL, .filter = NULL, .serviceLanguage = NULL, .ignoreServiceLanguage = false}

C Macro to create a empty celix_service_filter_options_t type.

#define CELIX_EMPTY_SERVICE_REGISTRATION_OPTIONS

Value:

{ .svc = NULL, \
    .factory = NULL, \
    .serviceName = NULL, \
    .properties = NULL, \
    .serviceLanguage = NULL, \
    .serviceVersion = NULL }

C Macro to create a empty celix_service_registration_options_t type.

#define CELIX_EMPTY_SERVICE_TRACKING_OPTIONS

Value:

{ .filter.serviceName = NULL, \
    .filter.versionRange = NULL, \
    .filter.filter = NULL, \
    .filter.serviceLanguage = NULL, \
    .filter.ignoreServiceLanguage = false, \
    .callbackHandle = NULL, \
    .set = NULL, \
    .add = NULL, \
    .remove = NULL, \
    .setWithProperties = NULL, \
    .addWithProperties = NULL, \
    .removeWithProperties = NULL, \
    .setWithOwner = NULL, \
    .addWithOwner = NULL, \
    .removeWithOwner = NULL}

C Macro to create a empty celix_service_tracking_options_t type.

#define CELIX_EMPTY_SERVICE_USE_OPTIONS

Value:

{.filter.serviceName = NULL, \
    .filter.versionRange = NULL, \
    .filter.filter = NULL, \
    .filter.serviceLanguage = NULL, \
    .waitTimeoutInSeconds = 0.0F, \
    .callbackHandle = NULL, \
    .use = NULL, \
    .useWithProperties = NULL, \
    .useWithOwner = NULL}

C Macro to create a empty celix_service_use_options_t type.

#define OPTS_INIT

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

Typedef Documentation

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.

typedef struct celix_service_filter_options celix_service_filter_options_t

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

typedef struct celix_service_registration_options celix_service_registration_options_t

Service Registration Options when registering services to the Celix framework.

typedef struct celix_service_tracker_info celix_service_tracker_info_t

Service Tracker Info provided to the service tracker tracker callbacks.

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.

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

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

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_bundle_t* celix_bundleContext_getBundle ( celix_bundle_context_t * ctx )

Returns the bundle for this bundle context.

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.

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

Gets the config property - or environment variable if the config property does not exist - for the provided name.

Parameters

key	The key of the property to receive.
defaultVal	The default value to use if the property is not found (can be NULL).

Returns: The property value for the provided key or the provided defaultValue is the key is not found.

bool celix_bundleContext_getPropertyAsBool	(	celix_bundle_context_t *	ctx,
		const char *	key,
		bool	defaultValue
	)

Gets the config property as converts it to bool. If the property is not a valid bool, the defaultValue will be returned. The rest of the behaviour is the same as celix_bundleContext_getProperty.

Parameters

key	The key of the property to receive.
defaultVal	The default value to use if the property is not found.

Returns: The property value for the provided key or the provided defaultValue is the key is not found.

double celix_bundleContext_getPropertyAsDouble	(	celix_bundle_context_t *	ctx,
		const char *	key,
		double	defaultValue
	)

Gets the config property as converts it to double. If the property is not a valid double, the defaultValue will be returned. The rest of the behaviour is the same as celix_bundleContext_getProperty.

Parameters

key	The key of the property to receive.
defaultVal	The default value to use if the property is not found.

Returns: The property value for the provided key or the provided defaultValue is the key is not found.

long celix_bundleContext_getPropertyAsLong	(	celix_bundle_context_t *	ctx,
		const char *	key,
		long	defaultValue
	)

Gets the config property as converts it to long. If the property is not a valid long, the defaultValue will be returned. The rest of the behaviour is the same as celix_bundleContext_getProperty.

Parameters

key	The key of the property to receive.
defaultVal	The default value to use if the property is not found.

Returns: The property value for the provided key or the provided defaultValue is the key is not found.

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

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

Parameters

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

bool celix_bundleContext_isBundleInstalled	(	celix_bundle_context_t *	ctx,
		long	bndId
	)

Check if whether a bundle is installed.

Parameters

ctx	The bundle context.
bndId	The bundle id to check

Returns: true if the bundle is installed.

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 0).

Parameters

ctx	The bundle context

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

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.

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 < 0 if the registration was unsuccessful.

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 (for the C language). 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.

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.

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.

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 < 0 if the registration was unsuccessful.

bool celix_bundleContext_startBundle	(	celix_bundle_context_t *	ctx,
		long	bundleId
	)

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

Parameters

ctx	The bundle context
bundleId	The bundle id to start.

Returns: true if the bundle is found & correctly started. False if not.

bool celix_bundleContext_stopBundle	(	celix_bundle_context_t *	ctx,
		long	bundleId
	)

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

Parameters

ctx	The bundle context
bundleId	The bundle id to stop.

Returns: true if the bundle is found & correctly stop. False if not.

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.

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

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.

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.

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)

Parameters

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

Returns: The bundle tracker id (>=0) or < 0 if unsuccessful.

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.

Parameters

ctx	The bundle context.
serviceName	The required service name to track
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.

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.

Parameters

ctx	The bundle context.
serviceName	The required service name to track
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.

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.

Parameters

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

Returns: the tracker id (>=0) or < 0 if unsuccessful.

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.

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

bool celix_bundleContext_uninstallBundle	(	celix_bundle_context_t *	ctx,
		long	bundleId
	)

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

Parameters

ctx	The bundle context
bundleId	The bundle id to uninstall.

Returns: true if the bundle is correctly uninstalled. False if not.

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

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 if it is in the active (started) state The provided callback will be called if the bundle is found and in the active (started) state.

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.

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

Use the currently active (started) bundles. The provided callback will be called for all the currently started bundles (excluding 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.

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.

This function will block till 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.

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

This function will block till 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.

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

This function will block till 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.

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.

This function will block till 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.

bool celix_bundleContext_useServiceWithOptions	(	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.

This function will block till 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.

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation