celix_dm_component.h File Reference

#include <stdbool.h>
#include "celix_types.h"
#include "celix_errno.h"
#include "properties.h"
#include "array_list.h"
#include "celix_dm_info.h"

Include dependency graph for celix_dm_component.h:

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

Go to the source code of this file.

Macros
#define	CELIX_DM_COMPONENT_UUID   "component.uuid"
#define	CELIX_DM_COMPONENT_MAX_ID_LENGTH   64
#define	CELIX_DM_COMPONENT_MAX_NAME_LENGTH   128
#define	CELIX_DM_COMPONENT_SET_IMPLEMENTATION_DESTROY_FUNCTION(dmCmp, type, destroy)
#define	CELIX_DM_COMPONENT_SET_CALLBACKS(dmCmp, type, init, start, stop, deinit)
#define	CELIX_DMCOMPONENT_SETCALLBACKS(dmCmp, type, init, start, stop, deinit)   CELIX_DM_COMPONENT_SET_CALLBACKS(dmCmp, type*, init, start, stop, deinit)

Typedefs
typedef enum celix_dm_component_state_enum	celix_dm_component_state_t
typedef int(*	celix_dm_cmp_lifecycle_fpt) (void *userData)
typedef void(*	celix_dm_cmp_impl_destroy_fpt) (void *)

Enumerations
enum	celix_dm_component_state_enum {   CELIX_DM_CMP_STATE_INACTIVE = 1, CELIX_DM_CMP_STATE_WAITING_FOR_REQUIRED = 2, CELIX_DM_CMP_STATE_INITIALIZING = 3, CELIX_DM_CMP_STATE_DEINITIALIZING = 4,   CELIX_DM_CMP_STATE_INITIALIZED_AND_WAITING_FOR_REQUIRED = 5, CELIX_DM_CMP_STATE_STARTING = 6, CELIX_DM_CMP_STATE_STOPPING = 7, CELIX_DM_CMP_STATE_TRACKING_OPTIONAL = 8,   CELIX_DM_CMP_STATE_SUSPENDING = 9, CELIX_DM_CMP_STATE_SUSPENDED = 10, CELIX_DM_CMP_STATE_RESUMING = 11, DM_CMP_STATE_INACTIVE = 1,   DM_CMP_STATE_WAITING_FOR_REQUIRED = 2, DM_CMP_STATE_INSTANTIATED_AND_WAITING_FOR_REQUIRED = 5, DM_CMP_STATE_TRACKING_OPTIONAL = 8 }

Functions
celix_dm_component_t *	celix_dmComponent_create (celix_bundle_context_t *context, const char *name)
celix_dm_component_t *	celix_dmComponent_createWithUUID (celix_bundle_context_t *context, const char *name, const char *UUID)
const char *	celix_dmComponent_getUUID (celix_dm_component_t *cmp)
void	celix_dmComponent_destroy (celix_dm_component_t *cmp)
void	celix_dmComponent_destroyAsync (celix_dm_component_t *cmp, void *doneData, void(*doneCallback)(void *))
celix_status_t	celix_dmComponent_setCLanguageProperty (celix_dm_component_t *component, bool setCLangProp)
celix_status_t	celix_dmComponent_addInterface (celix_dm_component_t *component, const char *serviceName, const char *serviceVersion, const void *service, celix_properties_t *properties)
celix_status_t	celix_dmComponent_removeInterface (celix_dm_component_t *component, const void *service)
celix_status_t	celix_dmComponent_setImplementation (celix_dm_component_t *component, void *implementation)
void	celix_dmComponent_setImplementationDestroyFunction (celix_dm_component_t *cmp, celix_dm_cmp_impl_destroy_fpt destroyFn)
celix_status_t	celix_dmComponent_getInterfaces (celix_dm_component_t *component, celix_array_list_t **servicesNames)
celix_status_t	celix_dmComponent_addServiceDependency (celix_dm_component_t *component, celix_dm_service_dependency_t *dep)
celix_status_t	celix_dmComponent_removeServiceDependency (celix_dm_component_t *component, celix_dm_service_dependency_t *dependency)
celix_dm_component_state_t	celix_dmComponent_currentState (celix_dm_component_t *cmp)
void *	celix_dmComponent_getImplementation (celix_dm_component_t *cmp)
celix_dm_cmp_impl_destroy_fpt	celix_dmComponent_getImplementationDestroyFunction (celix_dm_component_t *cmp)
const char *	celix_dmComponent_getName (celix_dm_component_t *cmp)
celix_bundle_context_t *	celix_dmComponent_getBundleContext (celix_dm_component_t *component)
celix_status_t	celix_dmComponent_setCallbacks (celix_dm_component_t *component, celix_dm_cmp_lifecycle_fpt init, celix_dm_cmp_lifecycle_fpt start, celix_dm_cmp_lifecycle_fpt stop, celix_dm_cmp_lifecycle_fpt deinit)
bool	celix_dmComponent_isActive (celix_dm_component_t *component)
const char *	celix_dmComponent_stateToString (celix_dm_component_state_t state)
celix_status_t	celix_dmComponent_getComponentInfo (celix_dm_component_t *component, celix_dm_component_info_t **infoOut)
void	celix_dmComponent_printComponentInfo (celix_dm_component_info_t *info, bool printFullInfo, bool useAnsiColors, FILE *stream)
void	celix_dmComponent_destroyComponentInfo (dm_component_info_pt info)

Macro Definition Documentation

CELIX_DM_COMPONENT_MAX_ID_LENGTH

#define CELIX_DM_COMPONENT_MAX_ID_LENGTH   64

CELIX_DM_COMPONENT_MAX_NAME_LENGTH

#define CELIX_DM_COMPONENT_MAX_NAME_LENGTH   128

CELIX_DM_COMPONENT_SET_CALLBACKS

#define CELIX_DM_COMPONENT_SET_CALLBACKS	(		dmCmp,
			type,
			init,
			start,
			stop,
			deinit
	)

Value:

    do {  \
        int (*_tmp_init)(type*)   = (init); \
        int (*_tmp_start)(type*)  = (start); \
        int (*_tmp_stop)(type*)   = (stop); \
        int (*_tmp_deinit)(type*) = (deinit); \
        celix_dmComponent_setCallbacks((dmCmp), (celix_dm_cmp_lifecycle_fpt)_tmp_init, (celix_dm_cmp_lifecycle_fpt)_tmp_start, (celix_dm_cmp_lifecycle_fpt)_tmp_stop, (celix_dm_cmp_lifecycle_fpt)_tmp_deinit); \
    } while(0)

Set the component life cycle callbacks using a MACRO for improving the type safety.

CELIX_DM_COMPONENT_SET_IMPLEMENTATION_DESTROY_FUNCTION

#define CELIX_DM_COMPONENT_SET_IMPLEMENTATION_DESTROY_FUNCTION	(		dmCmp,
			type,
			destroy
	)

Value:

    do {  \
        void (*_destroyFunction)(type*) = (destroy); \
        celix_dmComponent_setImplementationDestroyFunction((dmCmp), (void(*)(void*))_destroyFunction); \
    } while(0)

Configures the destroy function for the component implementation using a MACRO for improving the type safety.

CELIX_DM_COMPONENT_UUID

#define CELIX_DM_COMPONENT_UUID   "component.uuid"

CELIX_DMCOMPONENT_SETCALLBACKS

#define CELIX_DMCOMPONENT_SETCALLBACKS	(		dmCmp,
			type,
			init,
			start,
			stop,
			deinit
	)		CELIX_DM_COMPONENT_SET_CALLBACKS(dmCmp, type*, init, start, stop, deinit)

Deprecated, use CELIX_DM_COMPONENT_SET_CALLBACKS instead.

Typedef Documentation

celix_dm_cmp_impl_destroy_fpt

typedef void(* celix_dm_cmp_impl_destroy_fpt) (void *)

celix_dm_cmp_lifecycle_fpt

typedef int(* celix_dm_cmp_lifecycle_fpt) (void *userData)

celix_dm_component_state_t

typedef enum celix_dm_component_state_enum celix_dm_component_state_t

Enumeration Type Documentation

celix_dm_component_state_enum

enum celix_dm_component_state_enum

Enumerator
CELIX_DM_CMP_STATE_INACTIVE
CELIX_DM_CMP_STATE_WAITING_FOR_REQUIRED
CELIX_DM_CMP_STATE_INITIALIZING
CELIX_DM_CMP_STATE_DEINITIALIZING
CELIX_DM_CMP_STATE_INITIALIZED_AND_WAITING_FOR_REQUIRED
CELIX_DM_CMP_STATE_STARTING
CELIX_DM_CMP_STATE_STOPPING
CELIX_DM_CMP_STATE_TRACKING_OPTIONAL
CELIX_DM_CMP_STATE_SUSPENDING
CELIX_DM_CMP_STATE_SUSPENDED
CELIX_DM_CMP_STATE_RESUMING
DM_CMP_STATE_INACTIVE	Note this dm state enums are deprecated, but for now still supported.
DM_CMP_STATE_WAITING_FOR_REQUIRED
DM_CMP_STATE_INSTANTIATED_AND_WAITING_FOR_REQUIRED
DM_CMP_STATE_TRACKING_OPTIONAL

Function Documentation

celix_dmComponent_addInterface()

celix_status_t celix_dmComponent_addInterface	(	celix_dm_component_t *	component,
		const char *	serviceName,
		const char *	serviceVersion,
		const void *	service,
		celix_properties_t *	properties
	)

Adds a C interface to provide as service to the Celix framework.

Parameters

serviceName	the service name.
version	The version of the interface (e.g. "1.0.0"), Can be a NULL pointer.
properties	To (meta) properties to provide with the service. Can be a NULL pointer.

celix_dmComponent_addServiceDependency()

celix_status_t celix_dmComponent_addServiceDependency	(	celix_dm_component_t *	component,
		celix_dm_service_dependency_t *	dep
	)

Adds a C service dependency to the component

celix_dmComponent_create()

celix_dm_component_t* celix_dmComponent_create	(	celix_bundle_context_t *	context,
		const char *	name
	)

Creates a DM Component with a random generated UUID. Caller has ownership.

celix_dmComponent_createWithUUID()

celix_dm_component_t* celix_dmComponent_createWithUUID	(	celix_bundle_context_t *	context,
		const char *	name,
		const char *	UUID
	)

Creates a DM Component with a provided UUID. Caller has ownership.

celix_dmComponent_currentState()

celix_dm_component_state_t celix_dmComponent_currentState

(

celix_dm_component_t *

cmp

)

Returns the current state of the component.

celix_dmComponent_destroy()

void celix_dmComponent_destroy

(

celix_dm_component_t *

cmp

)

Destroys a DM Component

celix_dmComponent_destroyAsync()

void celix_dmComponent_destroyAsync	(	celix_dm_component_t *	cmp,
		void *	doneData,
		void(*)(void *)	doneCallback
	)

Destroys a DM Component on the event thread. Will call doneCallback (if not NULL) when done.

celix_dmComponent_destroyComponentInfo()

void celix_dmComponent_destroyComponentInfo

(

dm_component_info_pt

info

)

Destroys a DM Component info struct.

celix_dmComponent_getBundleContext()

celix_bundle_context_t* celix_dmComponent_getBundleContext

(

celix_dm_component_t *

component

)

Returns bundle context for the bundle where this DM component is part of.

celix_dmComponent_getComponentInfo()

celix_status_t celix_dmComponent_getComponentInfo	(	celix_dm_component_t *	component,
		celix_dm_component_info_t **	infoOut
	)

Create a DM Component info struct. Containing information about the component. Caller has ownership.

celix_dmComponent_getImplementation()

void* celix_dmComponent_getImplementation

(

celix_dm_component_t *

cmp

)

Returns the implementation of the component. e.g. the component handle/self/this pointer.

celix_dmComponent_getImplementationDestroyFunction()

celix_dm_cmp_impl_destroy_fpt celix_dmComponent_getImplementationDestroyFunction

(

celix_dm_component_t *

cmp

)

Returns the configured component implementation destroy function.

celix_dmComponent_getInterfaces()

celix_status_t celix_dmComponent_getInterfaces	(	celix_dm_component_t *	component,
		celix_array_list_t **	servicesNames
	)

Returns an arraylist of service names. The caller owns the arraylist and strings (char *)

celix_dmComponent_getName()

const char* celix_dmComponent_getName

(

celix_dm_component_t *

cmp

)

Returns the DM component name. This is used when printing information about the component.

celix_dmComponent_getUUID()

const char* celix_dmComponent_getUUID

(

celix_dm_component_t *

cmp

)

Get the UUID of the component.

celix_dmComponent_isActive()

bool celix_dmComponent_isActive

(

celix_dm_component_t *

component

)

celix_dmComponent_printComponentInfo()

void celix_dmComponent_printComponentInfo	(	celix_dm_component_info_t *	info,
		bool	printFullInfo,
		bool	useAnsiColors,
		FILE *	stream
	)

Print the component info to the provided stream.

Parameters

info	The component info to print.
printFullInfo	Whether to print the full info or summary.
useAnsiColors	Whether to use ansi colors when printing the component info.
stream	The stream to print to (e..g stdout).

celix_dmComponent_removeInterface()

celix_status_t celix_dmComponent_removeInterface	(	celix_dm_component_t *	component,
		const void *	service
	)

Removed a C interface from a component the Celix framework.

Parameters

serviceName

the service name.

Returns

CELIX_SUCCESS when removed, CELIX_ILLEGAL_ARGUMENT when the component does not provide the interface

celix_dmComponent_removeServiceDependency()

celix_status_t celix_dmComponent_removeServiceDependency	(	celix_dm_component_t *	component,
		celix_dm_service_dependency_t *	dependency
	)

Removes a C service dependency to the component

celix_dmComponent_setCallbacks()

celix_status_t celix_dmComponent_setCallbacks	(	celix_dm_component_t *	component,
		celix_dm_cmp_lifecycle_fpt	init,
		celix_dm_cmp_lifecycle_fpt	start,
		celix_dm_cmp_lifecycle_fpt	stop,
		celix_dm_cmp_lifecycle_fpt	deinit
	)

Set the component life cycle callbacks. The first argument will be the component implementation (

See also

component_getImplementation)

celix_dmComponent_setCLanguageProperty()

celix_status_t celix_dmComponent_setCLanguageProperty	(	celix_dm_component_t *	component,
		bool	setCLangProp
	)

Specify if a default 'service.lang=C' should be added to the properties of interfaces if no 'service.lang' has been provided. Default is false. Note that this should be set before using component_addInterface.

celix_dmComponent_setImplementation()

celix_status_t celix_dmComponent_setImplementation	(	celix_dm_component_t *	component,
		void *	implementation
	)

Sets the implementation of the component. e.g. the component handle/self/this pointer.

celix_dmComponent_setImplementationDestroyFunction()

void celix_dmComponent_setImplementationDestroyFunction	(	celix_dm_component_t *	cmp,
		celix_dm_cmp_impl_destroy_fpt	destroyFn
	)

Configures the destroy function for the component implementation.

If a destroy function for the component implementation is configured, this will be used when the component is removed from the dependency manager and component is successfully de-activated.

The destroy function will not be called if the component implementation is not set. e.g. if the celix_dmComponent_setImplementation is not called with a non NULL value.

celix_dmComponent_stateToString()

const char* celix_dmComponent_stateToString

(

celix_dm_component_state_t

state

)

Returns the string value of a provided state