pnoltes commented on code in PR #729:
URL: https://github.com/apache/celix/pull/729#discussion_r1501844538
##########
libs/framework/include/celix_bundle_context.h:
##########
@@ -393,50 +388,218 @@ CELIX_FRAMEWORK_EXPORT long
celix_bundleContext_findServiceWithOptions(celix_bun
CELIX_FRAMEWORK_EXPORT celix_array_list_t*
celix_bundleContext_findServicesWithOptions(celix_bundle_context_t *ctx, const
celix_service_filter_options_t *opts);
/**
- * @brief Track the highest ranking service with the provided serviceName.
+ * @brief 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.
+ *
+ * @param ctx The bundle context
+ * @param serviceId the service id.
+ * @param serviceName the service name of the service. Should match with the
registered service name of the provided service id (sanity check)
+ * @param callbackHandle The data pointer, which will be used in the callbacks
+ * @param use The callback, which will be called when service is retrieved.
+ * @param bool returns true if a service was found.
+ */
+CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useServiceWithId(
+ celix_bundle_context_t *ctx,
+ long serviceId,
+ const char* serviceName /*sanity check*/,
+ void *callbackHandle,
+ void (*use)(void *handle, void* svc)
+);
+
+/**
+ * @brief 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.
+ *
+ * @param ctx The bundle context
+ * @param serviceName the required service name.
+ * @param callbackHandle The data pointer, which will be used in the
callbacks
+ * @param use The callback, which will be called when service is retrieved.
+ * @return True if a service was found.
+ */
+CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useService(
+ celix_bundle_context_t *ctx,
+ const char* serviceName,
+ void *callbackHandle,
+ void (*use)(void *handle, void *svc)
+);
+
+/**
+ * @brief 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.
+ *
+ * @param ctx The bundle context
+ * @param serviceName the required service name.
+ * @param callbackHandle The data pointer, which will be used in the
callbacks
+ * @param use The callback, which will be called for every service found.
+ * @return The number of services found and called
+ */
+CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useServices(
+ celix_bundle_context_t *ctx,
+ const char* serviceName,
+ void *callbackHandle,
+ void (*use)(void *handle, void *svc)
+);
+
+/**
+ * @brief Service Use Options used to fine tune which services to use and
which callbacks to use.
+ *
+ * If multiple use callbacks are set, all set callbacks will be called for
every service found.
+ */
+typedef struct celix_service_use_options {
+ /**
+ * @brief The service filter options, used to setup the filter for the
service to track.
+ */
+ celix_service_filter_options_t filter CELIX_OPTS_INIT;
+
+ /**
+ * @brief An optional timeout (in seconds), if > 0 the use service call
will block until the timeout is expired or
+ * when at least one service is found. Note that it will be ignored when
use service on the event loop.
+ * Default (0)
+ *
+ * Only applicable when using the celix_bundleContext_useService or
+ * celix_bundleContext_useServiceWithOptions (use single service calls).
+ */
+ double waitTimeoutInSeconds CELIX_OPTS_INIT;
+
+ /**
+ * @brief The optional callback pointer used in all the provided callback
function (use, useWithProperties, and
+ * useWithOwner).
+ */
+ void* callbackHandle CELIX_OPTS_INIT;
+
+ /**
+ * @brief The optional use callback will be called when for every services
found conform the service filter options
+ * - in case of findServices - or only for the highest ranking service
found - in case of findService -.
+ *
+ * @param handle The callbackHandle pointer as provided in the service
tracker options.
+ * @param svc The service pointer of the highest ranking service.
+ */
+ void (*use)(void* handle, void* svc) CELIX_OPTS_INIT;
+
+ /**
+ * @brief The optional useWithProperties callback is handled as the use
callback, but with the addition that the
+ * service properties will also be provided to the callback.
+ */
+ void (*useWithProperties)(void* handle, void* svc, const
celix_properties_t* props) CELIX_OPTS_INIT;
+
+ /**
+ * @brief The optional useWithOwner callback is handled as the yse
callback, but with the addition that the service
+ * properties and the bundle owning the service will also be provided to
the callback.
+ */
+ void (*useWithOwner)(void* handle, void* svc, const celix_properties_t*
props, const celix_bundle_t* svcOwner)
+ CELIX_OPTS_INIT;
+ /**
+ * @brief 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.
+ */
+#define CELIX_SERVICE_USE_DIRECT (1)
+ /**
+ * @brief 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.
+ */
+#define CELIX_SERVICE_USE_SOD (2)
+ int flags CELIX_OPTS_INIT;
+} celix_service_use_options_t;
+
+#ifndef __cplusplus
+/*!
+ * @brief C Macro to create a empty celix_service_use_options_t type.
+ */
+#define CELIX_EMPTY_SERVICE_USE_OPTIONS {.filter.serviceName = NULL, \
+ .filter.versionRange = NULL, \
+ .filter.filter = NULL, \
+ .waitTimeoutInSeconds = 0.0F, \
+ .callbackHandle = NULL, \
+ .use = NULL, \
+ .useWithProperties = NULL, \
+ .useWithOwner = NULL, \
+ .flags=0}
+#endif
+
+/**
+ * @brief 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 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 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.
+ *
+ * @param ctx The bundle context.
+ * @param opts The required options. Note that the serviceName is required.
+ * @return True if a service was found.
+ */
+CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useServiceWithOptions(
+ celix_bundle_context_t *ctx,
+ const celix_service_use_options_t *opts);
+
+
+/**
+ * @brief 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.
+ *
+ * @param ctx The bundle context.
+ * @param opts The required options. Note that the serviceName is required.
+ * @return The number of services found and called
+ */
+CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useServicesWithOptions(
+ celix_bundle_context_t *ctx,
+ const celix_service_use_options_t *opts);
+
+/**
+ * @brief Track the highest ranking service 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.
*
* @param ctx The bundle context.
* @param serviceName The required service name to track.
* If NULL is all service are tracked.
- * @param callbackHandle The data pointer, which will be used in the callbacks
- * @param set is a required callback, which will be called when a new highest
ranking service is set.
* @return the tracker id (>=0) or < 0 if unsuccessful.
*/
-CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServiceAsync(
- celix_bundle_context_t *ctx,
- const char* serviceName,
- void* callbackHandle,
- void (*set)(void* handle, void* svc)
-);
+CELIX_FRAMEWORK_EXPORT long
celix_bundleContext_trackServiceAsync(celix_bundle_context_t* ctx, const char*
serviceName);
Review Comment:
Yeah you are right, not sure why i added the singular track services
functions.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: dev-unsubscr...@celix.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
