celix_dm_service_dependency.h File Reference

#include "celix_types.h"
#include "celix_errno.h"
#include "celix_threads.h"
#include "celix_dm_info.h"
#include "celix_framework_export.h"

Include dependency graph for celix_dm_service_dependency.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	celix_dm_service_dependency_callback_options

Macros
#define	CELIX_EMPTY_DM_SERVICE_DEPENDENCY_CALLBACK_OPTIONS

Typedefs
typedef enum celix_dm_service_dependency_strategy_enum	celix_dm_service_dependency_strategy_t
typedef int(*	celix_dm_service_update_fp) (void *handle, void *service)
typedef int(*	celix_dm_service_swap_fp) (void *handle, void *oldService, void *newService)
typedef int(*	celix_dm_service_update_with_props_fp) (void *handle, void *service, const celix_properties_t *props)
typedef int(*	celix_dm_service_swap_with_props_fp) (void *handle, void *oldService, void *newService, const celix_properties_t *newProps)
typedef struct celix_dm_service_dependency_callback_options	celix_dm_service_dependency_callback_options_t

Enumerations
enum	celix_dm_service_dependency_strategy_enum { DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING, DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND }

Functions
CELIX_FRAMEWORK_EXPORT celix_dm_service_dependency_t *	celix_dmServiceDependency_create (void)
CELIX_FRAMEWORK_EXPORT void	celix_dmServiceDependency_destroy (celix_dm_service_dependency_t *dep)
CELIX_FRAMEWORK_EXPORT celix_status_t	celix_dmServiceDependency_setRequired (celix_dm_service_dependency_t *dependency, bool required)
CELIX_FRAMEWORK_DEPRECATED_EXPORT celix_status_t	celix_dmServiceDependency_setAddCLanguageFilter (celix_dm_service_dependency_t *dependency, bool addCLangFilter)
CELIX_FRAMEWORK_EXPORT celix_status_t	celix_dmServiceDependency_setStrategy (celix_dm_service_dependency_t *dependency, celix_dm_service_dependency_strategy_t strategy)
CELIX_FRAMEWORK_EXPORT celix_dm_service_dependency_strategy_t	celix_dmServiceDependency_getStrategy (celix_dm_service_dependency_t *dependency)
CELIX_FRAMEWORK_EXPORT celix_status_t	celix_dmServiceDependency_setService (celix_dm_service_dependency_t *dependency, const char *serviceName, const char *serviceVersionRange, const char *filter)
const CELIX_FRAMEWORK_EXPORT char *	celix_dmServiceDependency_getFilter (celix_dm_service_dependency_t *dependency)
CELIX_FRAMEWORK_EXPORT celix_status_t	celix_dmServiceDependency_setCallback (celix_dm_service_dependency_t *dependency, celix_dm_service_update_fp set)
CELIX_FRAMEWORK_EXPORT celix_status_t	celix_dmServiceDependency_setCallbackWithProperties (celix_dm_service_dependency_t *dependency, celix_dm_service_update_with_props_fp set)
CELIX_FRAMEWORK_EXPORT celix_status_t	celix_dmServiceDependency_setCallbacksWithOptions (celix_dm_service_dependency_t *dependency, const celix_dm_service_dependency_callback_options_t *opts)
CELIX_FRAMEWORK_EXPORT celix_status_t	celix_dmServiceDependency_setCallbackHandle (celix_dm_service_dependency_t *dependency, void *handle)
CELIX_FRAMEWORK_EXPORT dm_service_dependency_info_t *	celix_dmServiceDependency_createInfo (celix_dm_service_dependency_t *dep)
CELIX_FRAMEWORK_EXPORT void	celix_dmServiceDependency_destroyInfo (celix_dm_service_dependency_t *dep, dm_service_dependency_info_t *info)

Macro Definition Documentation

CELIX_EMPTY_DM_SERVICE_DEPENDENCY_CALLBACK_OPTIONS

#define CELIX_EMPTY_DM_SERVICE_DEPENDENCY_CALLBACK_OPTIONS

Value:

    { .set = NULL, \
    .add = NULL, \
    .remove = NULL, \
    .swap = NULL, \
    .setWithProps = NULL, \
    .addWithProps = NULL, \
    .removeWithProps = NULL, \
    .swapWithProps = NULL }

Typedef Documentation

celix_dm_service_dependency_callback_options_t

typedef struct celix_dm_service_dependency_callback_options celix_dm_service_dependency_callback_options_t

celix_dm_service_dependency_strategy_t

typedef enum celix_dm_service_dependency_strategy_enum celix_dm_service_dependency_strategy_t

celix_dm_service_swap_fp

typedef int(* celix_dm_service_swap_fp) (void *handle, void *oldService, void *newService)

celix_dm_service_swap_with_props_fp

typedef int(* celix_dm_service_swap_with_props_fp) (void *handle, void *oldService, void *newService, const celix_properties_t *newProps)

celix_dm_service_update_fp

typedef int(* celix_dm_service_update_fp) (void *handle, void *service)

celix_dm_service_update_with_props_fp

typedef int(* celix_dm_service_update_with_props_fp) (void *handle, void *service, const celix_properties_t *props)

Enumeration Type Documentation

celix_dm_service_dependency_strategy_enum

enum celix_dm_service_dependency_strategy_enum

Enumerator
DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING
DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND

Function Documentation

celix_dmServiceDependency_create()

CELIX_FRAMEWORK_EXPORT celix_dm_service_dependency_t* celix_dmServiceDependency_create

(

void

)

Create a service dependency. Caller has ownership.

Warning

The dmServiceDependency is not thread safe when constructing or modifying. The handling of service updates is thread safe.

celix_dmServiceDependency_createInfo()

CELIX_FRAMEWORK_EXPORT dm_service_dependency_info_t* celix_dmServiceDependency_createInfo

(

celix_dm_service_dependency_t *

dep

)

Creates a service dependency info. The service dependency info struct contains information about the service dependency. The caller is the owner

celix_dmServiceDependency_destroy()

CELIX_FRAMEWORK_EXPORT void celix_dmServiceDependency_destroy

(

celix_dm_service_dependency_t *

dep

)

Destroys a service dependency. Will normally be done the by the DM Component.

Can only be called if the serviceDependency is disabled (note that a service dependency not added to a component is disabled).

celix_dmServiceDependency_destroyInfo()

CELIX_FRAMEWORK_EXPORT void celix_dmServiceDependency_destroyInfo	(	celix_dm_service_dependency_t *	dep,
		dm_service_dependency_info_t *	info
	)

Destroy a provided service dependency info struct.

celix_dmServiceDependency_getFilter()

const CELIX_FRAMEWORK_EXPORT char* celix_dmServiceDependency_getFilter

(

celix_dm_service_dependency_t *

dependency

)

Returns the service dependency filter.

celix_dmServiceDependency_getStrategy()

CELIX_FRAMEWORK_EXPORT celix_dm_service_dependency_strategy_t celix_dmServiceDependency_getStrategy

(

celix_dm_service_dependency_t *

dependency

)

Return the service dependency update strategy.

celix_dmServiceDependency_setAddCLanguageFilter()

CELIX_FRAMEWORK_DEPRECATED_EXPORT celix_status_t celix_dmServiceDependency_setAddCLanguageFilter	(	celix_dm_service_dependency_t *	dependency,
		bool	addCLangFilter
	)

Specify if the service dependency should add a C language filter for this dependency if no "service.lang" part is found the in the provided filter. Default is false

celix_dmServiceDependency_setCallback()

CELIX_FRAMEWORK_EXPORT celix_status_t celix_dmServiceDependency_setCallback	(	celix_dm_service_dependency_t *	dependency,
		celix_dm_service_update_fp	set
	)

Set the set callbacks when services specified by the service dependency The first argument of the callbacks will be the component implement (

See also

component_getImplementation) The second the argument a pointer to an instance of a service struct of the specified service dependency.

celix_dmServiceDependency_setCallbackHandle()

CELIX_FRAMEWORK_EXPORT celix_status_t celix_dmServiceDependency_setCallbackHandle	(	celix_dm_service_dependency_t *	dependency,
		void *	handle
	)

Set the callback handle to be used in the callbacks. Note that this normally should not be set, because the result of component_getImplementation() is used This can be used in rare cases when the callbacks are actually interceptors. e.g. in the case of C++ support.

celix_dmServiceDependency_setCallbacksWithOptions()

CELIX_FRAMEWORK_EXPORT celix_status_t celix_dmServiceDependency_setCallbacksWithOptions	(	celix_dm_service_dependency_t *	dependency,
		const celix_dm_service_dependency_callback_options_t *	opts
	)

Set the set, add, change, remove and swap function callbacks when services specified by the service dependency are (respectively) set, added, changed, removed or swapped.

The version with the WithProps suffix will be called with as third argument the service properties.

celix_dmServiceDependency_setCallbackWithProperties()

CELIX_FRAMEWORK_EXPORT celix_status_t celix_dmServiceDependency_setCallbackWithProperties	(	celix_dm_service_dependency_t *	dependency,
		celix_dm_service_update_with_props_fp	set
	)

Set the set function callbacks when services specified by the service dependency The first argument of the callbacks will be the component implement (

See also

component_getImplementation) The second argument of th callbacks will be a pointer to an instance of a service struct of the specified service dependency. The third argument of th callbacks will be a pointer to a service properties of the a service instance of the specified service dependency.

celix_dmServiceDependency_setRequired()

CELIX_FRAMEWORK_EXPORT celix_status_t celix_dmServiceDependency_setRequired	(	celix_dm_service_dependency_t *	dependency,
		bool	required
	)

Specify if the service dependency is required. default is false

celix_dmServiceDependency_setService()

CELIX_FRAMEWORK_EXPORT celix_status_t celix_dmServiceDependency_setService	(	celix_dm_service_dependency_t *	dependency,
		const char *	serviceName,
		const char *	serviceVersionRange,
		const char *	filter
	)

Set the service name, version range and filter.

Parameters

serviceName	The service name. Must have a value.
serviceVersionRange	The service version range, can be a NULL pointer.
filter	The (additional) filter to use (e.g. "(location=front)"). Can be a NULL pointer.

celix_dmServiceDependency_setStrategy()

CELIX_FRAMEWORK_EXPORT celix_status_t celix_dmServiceDependency_setStrategy	(	celix_dm_service_dependency_t *	dependency,
		celix_dm_service_dependency_strategy_t	strategy
	)

Specify if the service dependency update strategy.

The DM_SERVICE_DEPENDENCY_STRATEGY_LOCKING strategy notifies the component in case the dependencies set changes (e.g. a dependency is added/removed): the component is responsible for protecting via locks the dependencies list and check (always under lock) if the service he's depending on is still available.

The DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND (default when no strategy is explicitly set) reliefs the programmer from dealing with service dependencies' consistency issues: in case this strategy is adopted, the component is stopped and restarted (i.e. temporarily suspended) upon service dependencies' changes.

Default strategy is DM_SERVICE_DEPENDENCY_STRATEGY_SUSPEND