libs/framework/include/celix_bundle_activator.h - celix - Git at Google

 /*
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
  * regarding copyright ownership.  The ASF licenses this file
  * to you under the Apache License, Version 2.0 (the
  * "License"); you may not use this file except in compliance
  * with the License.  You may obtain a copy of the License at
  *
  *   http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing,
  * software distributed under the License is distributed on an
  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  *  KIND, either express or implied.  See the License for the
  * specific language governing permissions and limitations
  * under the License.
  */

 #ifndef CELIX_BUNDLE_ACTIVATOR_H_
 #define CELIX_BUNDLE_ACTIVATOR_H_

 #include <stdlib.h>

 #include "celix_bundle_context.h"
 #include "celix_dependency_manager.h"
 #include "celix_dm_component.h"
 #include "celix_dm_service_dependency.h"
 #include "celix_constants.h"

 #if defined(__linux__) || defined(__APPLE__)
 //always export bundle activator symbols
 #define CELIX_BUNDLE_ACTIVATOR_EXPORT __attribute__((visibility("default")))
 #else
 #define CELIX_BUNDLE_ACTIVATOR_EXPORT
 #endif

 #ifdef __cplusplus
 extern "C" {
 #endif

 /**
  * @brief Called when this bundle is started so the bundle can create an instance for its activator.
  *
  * The framework does not assume any type for the activator instance, this is implementation specific.
  * The activator instance is handle as a void pointer by the framework, the implementation must cast it to the
  * implementation specific type.
  *
  * @param ctx The execution context of the bundle being started.
  * @param[out] userData A pointer to the specific activator instance used by this bundle.
  *
  * @return Status code indication failure or success:
  * 		- CELIX_SUCCESS when no errors are encountered.
  * 		- Any other status code will mark the bundle as stopped and the framework will remove this
  * 		  bundle's listeners, unregister all services, and release all services used by this bundle.
  */
 CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_create(celix_bundle_context_t *ctx, void **userData);

 /**
  * @brief Called when this bundle is started so the Framework can perform the bundle-specific activities necessary
  * to start this bundle.
  *
  * This method can be used to register services or to allocate any resources that this bundle needs.
  *
  * <p>
  * This method must complete and return to its caller in a timely manner.
  *
  * @param userData The activator instance to be used.
  * @param ctx The execution context of the bundle being started.
  *
  * @return Status code indication failure or success:
  * 		- CELIX_SUCCESS when no errors are encountered.
  * 		- Any other status code will mark the bundle as stopped and the framework will remove this
  * 		  bundle's listeners, unregister all services, and release all services used by this bundle.
  */
 CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_start(void *userData, celix_bundle_context_t *ctx);

 /**
  * @brief Called when this bundle is stopped so the Framework can perform the bundle-specific activities necessary
  * to stop the bundle.
  *
  * In general, this method should undo the work that the <code>bundleActivator_start()</code>
  * function started. There should be no active threads that were started by this bundle when this bundle returns.
  * A stopped bundle must not call any Framework objects.
  *
  * <p>
  * This method must complete and return to its caller in a timely manner.
  *
  * @param userData The activator instance to be used.
  * @param ctx The execution context of the bundle being stopped.
  *
  * @return Status code indication failure or success:
  * 		- CELIX_SUCCESS when no errors are encountered.
  * 		- Any other status code will mark the bundle as stopped and the framework will remove this
  * 		  bundle's listeners, unregister all services, and release all services used by this bundle.
  */
 CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_stop(void *userData, celix_bundle_context_t *ctx);

 /**
  * @brief Called when this bundle is stopped so the bundle can destroy the instance of its activator.
  *
  * In general, this method should undo the work that the <code>bundleActivator_create()</code> function initialized.
  *
  * <p>
  * This method must complete and return to its caller in a timely manner.
  *
  * @param userData The activator instance to be used.
  * @param ctx The execution context of the bundle being stopped.
  *
  * @return Status code indication failure or success:
  * 		- CELIX_SUCCESS when no errors are encountered.
  * 		- Any other status code will mark the bundle as stopped and the framework will remove this
  * 		  bundle's listeners, unregister all services, and release all services used by this bundle.
  */
 CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_destroy(void *userData, celix_bundle_context_t* ctx);

 /**
  * @brief This macro generates the required bundle activator functions for C.
  *
  * This can be used to more type safe bundle activator entries.
  *
  * The macro will create the following bundle activator functions:
  * - bundleActivator_create which allocates a pointer to the provided type.
  * - bundleActivator_start/stop which will call the respectively provided typed start/stop functions.
  * - bundleActivator_destroy will free the allocated for the provided type.
  *
  * After the (optional) provided activator stop callback is called, the generated `celix_bundleActivator_stop`
  * function will remove all components from the bundle's dependency manager
  * (using `celix_dependencyManager_removeAllComponents). This will ensure that dependency manager components can be
  * used without explicitly programming their removal and destroy functionality.
  *
  * @param actType The activator type (e.g. 'struct shell_activator').
  * @param actStart The optional activator actStart function with the following signature:
  *                 celix_status_t (*)(<actType>*, celix_bundle_context_t*).
  * @param actStop The optional activator actStop function with the following signature:
  *                celix_status_t (*)(<actType>*, celix_bundle_context_t*).
  */
 #define CELIX_GEN_BUNDLE_ACTIVATOR(actType, actStart, actStop)                                                         \
                                                                                                                        \
 celix_status_t celix_bundleActivator_create(celix_bundle_context_t *ctx, void **userData) {                            \
     celix_status_t status = CELIX_SUCCESS;                                                                             \
     void* data = calloc(1, sizeof(actType));                                                                           \
     if (data != NULL) {                                                                                                \
         *userData = data;                                                                                              \
     } else {                                                                                                           \
         status = CELIX_ENOMEM;                                                                                         \
     }                                                                                                                  \
     return status;                                                                                                     \
 }                                                                                                                      \
                                                                                                                        \
 celix_status_t celix_bundleActivator_start(void *userData, celix_bundle_context_t *ctx) {                              \
     celix_status_t status = CELIX_SUCCESS;                                                                             \
     celix_status_t (*fn)(actType*, celix_bundle_context_t*) = (actStart);                                              \
     if (fn != NULL) {                                                                                                  \
         status = fn((actType*)userData, ctx);                                                                          \
     }                                                                                                                  \
     return status;                                                                                                     \
 }                                                                                                                      \
                                                                                                                        \
 celix_status_t celix_bundleActivator_stop(void *userData, celix_bundle_context_t *ctx) {                               \
     celix_status_t status = CELIX_SUCCESS;                                                                             \
     celix_status_t (*fn)(actType*, celix_bundle_context_t*) = (actStop);                                               \
     if (fn != NULL) {                                                                                                  \
         status = fn((actType*)userData, ctx);                                                                          \
     }                                                                                                                  \
     celix_dependency_manager_t* mng = celix_bundleContext_getDependencyManager(ctx);                                   \
     celix_dependencyManager_removeAllComponents(mng);                                                                  \
     return status;                                                                                                     \
 }                                                                                                                      \
                                                                                                                        \
 celix_status_t celix_bundleActivator_destroy(void *userData, celix_bundle_context_t *ctx) {                            \
     celix_bundleContext_waitForEvents(ctx);                                                                            \
     free(userData);                                                                                                    \
     return CELIX_SUCCESS;                                                                                              \
 }

 #ifdef __cplusplus
 }
 #endif

 #endif /* CELIX_BUNDLE_ACTIVATOR_H_ */
	/*
	* Licensed to the Apache Software Foundation (ASF) under one
	* or more contributor license agreements. See the NOTICE file
	* distributed with this work for additional information
	* regarding copyright ownership. The ASF licenses this file
	* to you under the Apache License, Version 2.0 (the
	* "License"); you may not use this file except in compliance
	* with the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing,
	* software distributed under the License is distributed on an
	* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	* KIND, either express or implied. See the License for the
	* specific language governing permissions and limitations
	* under the License.
	*/

	#ifndef CELIX_BUNDLE_ACTIVATOR_H_
	#define CELIX_BUNDLE_ACTIVATOR_H_

	#include <stdlib.h>

	#include "celix_bundle_context.h"
	#include "celix_dependency_manager.h"
	#include "celix_dm_component.h"
	#include "celix_dm_service_dependency.h"
	#include "celix_constants.h"

	#if defined(__linux__) \|\| defined(__APPLE__)
	//always export bundle activator symbols
	#define CELIX_BUNDLE_ACTIVATOR_EXPORT __attribute__((visibility("default")))
	#else
	#define CELIX_BUNDLE_ACTIVATOR_EXPORT
	#endif

	#ifdef __cplusplus
	extern "C" {
	#endif

	/**
	* @brief Called when this bundle is started so the bundle can create an instance for its activator.
	*
	* The framework does not assume any type for the activator instance, this is implementation specific.
	* The activator instance is handle as a void pointer by the framework, the implementation must cast it to the
	* implementation specific type.
	*
	* @param ctx The execution context of the bundle being started.
	* @param[out] userData A pointer to the specific activator instance used by this bundle.
	*
	* @return Status code indication failure or success:
	* - CELIX_SUCCESS when no errors are encountered.
	* - Any other status code will mark the bundle as stopped and the framework will remove this
	* bundle's listeners, unregister all services, and release all services used by this bundle.
	*/
	CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_create(celix_bundle_context_t ctx, void *userData);

	/**
	* @brief Called when this bundle is started so the Framework can perform the bundle-specific activities necessary
	* to start this bundle.
	*
	* This method can be used to register services or to allocate any resources that this bundle needs.
	*
	* <p>
	* This method must complete and return to its caller in a timely manner.
	*
	* @param userData The activator instance to be used.
	* @param ctx The execution context of the bundle being started.
	*
	* @return Status code indication failure or success:
	* - CELIX_SUCCESS when no errors are encountered.
	* - Any other status code will mark the bundle as stopped and the framework will remove this
	* bundle's listeners, unregister all services, and release all services used by this bundle.
	*/
	CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_start(void userData, celix_bundle_context_t ctx);

	/**
	* @brief Called when this bundle is stopped so the Framework can perform the bundle-specific activities necessary
	* to stop the bundle.
	*
	* In general, this method should undo the work that the <code>bundleActivator_start()</code>
	* function started. There should be no active threads that were started by this bundle when this bundle returns.
	* A stopped bundle must not call any Framework objects.
	*
	* <p>
	* This method must complete and return to its caller in a timely manner.
	*
	* @param userData The activator instance to be used.
	* @param ctx The execution context of the bundle being stopped.
	*
	* @return Status code indication failure or success:
	* - CELIX_SUCCESS when no errors are encountered.
	* - Any other status code will mark the bundle as stopped and the framework will remove this
	* bundle's listeners, unregister all services, and release all services used by this bundle.
	*/
	CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_stop(void userData, celix_bundle_context_t ctx);

	/**
	* @brief Called when this bundle is stopped so the bundle can destroy the instance of its activator.
	*
	* In general, this method should undo the work that the <code>bundleActivator_create()</code> function initialized.
	*
	* <p>
	* This method must complete and return to its caller in a timely manner.
	*
	* @param userData The activator instance to be used.
	* @param ctx The execution context of the bundle being stopped.
	*
	* @return Status code indication failure or success:
	* - CELIX_SUCCESS when no errors are encountered.
	* - Any other status code will mark the bundle as stopped and the framework will remove this
	* bundle's listeners, unregister all services, and release all services used by this bundle.
	*/
	CELIX_BUNDLE_ACTIVATOR_EXPORT celix_status_t celix_bundleActivator_destroy(void userData, celix_bundle_context_t ctx);

	/**
	* @brief This macro generates the required bundle activator functions for C.
	*
	* This can be used to more type safe bundle activator entries.
	*
	* The macro will create the following bundle activator functions:
	* - bundleActivator_create which allocates a pointer to the provided type.
	* - bundleActivator_start/stop which will call the respectively provided typed start/stop functions.
	* - bundleActivator_destroy will free the allocated for the provided type.
	*
	* After the (optional) provided activator stop callback is called, the generated `celix_bundleActivator_stop`
	* function will remove all components from the bundle's dependency manager
	* (using `celix_dependencyManager_removeAllComponents). This will ensure that dependency manager components can be
	* used without explicitly programming their removal and destroy functionality.
	*
	* @param actType The activator type (e.g. 'struct shell_activator').
	* @param actStart The optional activator actStart function with the following signature:
	* celix_status_t ()(<actType>, celix_bundle_context_t*).
	* @param actStop The optional activator actStop function with the following signature:
	* celix_status_t ()(<actType>, celix_bundle_context_t*).
	*/
	#define CELIX_GEN_BUNDLE_ACTIVATOR(actType, actStart, actStop) \
	\
	celix_status_t celix_bundleActivator_create(celix_bundle_context_t ctx, void *userData) { \
	celix_status_t status = CELIX_SUCCESS; \
	void* data = calloc(1, sizeof(actType)); \
	if (data != NULL) { \
	*userData = data; \
	} else { \
	status = CELIX_ENOMEM; \
	} \
	return status; \
	} \
	\
	celix_status_t celix_bundleActivator_start(void userData, celix_bundle_context_t ctx) { \
	celix_status_t status = CELIX_SUCCESS; \
	celix_status_t (fn)(actType, celix_bundle_context_t*) = (actStart); \
	if (fn != NULL) { \
	status = fn((actType*)userData, ctx); \
	} \
	return status; \
	} \
	\
	celix_status_t celix_bundleActivator_stop(void userData, celix_bundle_context_t ctx) { \
	celix_status_t status = CELIX_SUCCESS; \
	celix_status_t (fn)(actType, celix_bundle_context_t*) = (actStop); \
	if (fn != NULL) { \
	status = fn((actType*)userData, ctx); \
	} \
	celix_dependency_manager_t* mng = celix_bundleContext_getDependencyManager(ctx); \
	celix_dependencyManager_removeAllComponents(mng); \
	return status; \
	} \
	\
	celix_status_t celix_bundleActivator_destroy(void userData, celix_bundle_context_t ctx) { \
	celix_bundleContext_waitForEvents(ctx); \
	free(userData); \
	return CELIX_SUCCESS; \
	}

	#ifdef __cplusplus
	}
	#endif

	#endif /* CELIX_BUNDLE_ACTIVATOR_H_ */