celix_bundle_context.h

Go to the documentation of this file.

/*
 * 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_CONTEXT_H_
#define CELIX_BUNDLE_CONTEXT_H_
 
#include "celix_bundle_context_type.h"
#include "celix_framework_export.h"
#include "celix_filter.h"
#include "celix_service_factory.h"
#include "celix_bundle_event.h"
#include "celix_log_level.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifdef __cplusplus
#define CELIX_OPTS_INIT {}
#else
#define CELIX_OPTS_INIT
#endif
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceAsync(celix_bundle_context_t *ctx, void *svc, const char* serviceName, celix_properties_t *properties);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerService(celix_bundle_context_t *ctx, void *svc, const char* serviceName, celix_properties_t *properties);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceFactoryAsync(celix_bundle_context_t *ctx, celix_service_factory_t *factory, const char* serviceName, celix_properties_t *props);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceFactory(celix_bundle_context_t *ctx, celix_service_factory_t *factory, const char* serviceName, celix_properties_t *props);
 
typedef struct celix_service_registration_options {
    void *svc CELIX_OPTS_INIT;
 
    celix_service_factory_t *factory CELIX_OPTS_INIT;
 
    const char* serviceName CELIX_OPTS_INIT;
 
    celix_properties_t *properties CELIX_OPTS_INIT;
 
    const char* serviceVersion CELIX_OPTS_INIT;
 
     void *asyncData CELIX_OPTS_INIT;
 
    void (*asyncCallback)(void *data, long serviceId) CELIX_OPTS_INIT;
} celix_service_registration_options_t;
 
#ifndef __cplusplus
 
#define CELIX_EMPTY_SERVICE_REGISTRATION_OPTIONS { .svc = NULL, \
    .factory = NULL, \
    .serviceName = NULL, \
    .properties = NULL, \
    .serviceVersion = NULL, \
    .asyncData = NULL, \
    .asyncCallback = NULL }
#endif
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceWithOptionsAsync(celix_bundle_context_t *ctx, const celix_service_registration_options_t *opts);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_registerServiceWithOptions(celix_bundle_context_t *ctx, const celix_service_registration_options_t *opts);
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncRegistration(celix_bundle_context_t *ctx, long serviceId);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_isServiceRegistered(celix_bundle_context_t *ctx, long serviceId);
 
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_unregisterService(celix_bundle_context_t *ctx, long serviceId);
 
typedef struct celix_service_registration_guard {
    celix_bundle_context_t* ctx;
    long svcId;
} celix_service_registration_guard_t;
 
static CELIX_UNUSED inline celix_service_registration_guard_t
celix_serviceRegistrationGuard_init(celix_bundle_context_t* ctx, long serviceId) {
    return (celix_service_registration_guard_t) { .ctx = ctx, .svcId = serviceId };
}
 
static CELIX_UNUSED inline void celix_serviceRegistrationGuard_deinit(celix_service_registration_guard_t* reg) {
    if (reg->svcId >= 0) {
        celix_bundleContext_unregisterService(reg->ctx, reg->svcId);
    }
}
 
CELIX_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(celix_service_registration_guard_t, celix_serviceRegistrationGuard_deinit)
 
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_unregisterServiceAsync(celix_bundle_context_t *ctx, long serviceId, void* doneData, void (*doneCallback)(void* doneData));
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncUnregistration(celix_bundle_context_t *ctx, long serviceId);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_findService(celix_bundle_context_t *ctx, const char* serviceName);
 
CELIX_FRAMEWORK_EXPORT celix_array_list_t* celix_bundleContext_findServices(celix_bundle_context_t *ctx, const char* serviceName);
 
typedef struct celix_service_filter_options {
    const char* serviceName CELIX_OPTS_INIT;
 
    const char* versionRange CELIX_OPTS_INIT;
 
    const char* filter CELIX_OPTS_INIT;
} celix_service_filter_options_t;
 
#ifndef __cplusplus
 
#define CELIX_EMPTY_SERVICE_FILTER_OPTIONS {.serviceName = NULL, .versionRange = NULL, .filter = NULL}
#endif
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_findServiceWithOptions(celix_bundle_context_t* ctx,
                                                                       const celix_service_filter_options_t* opts);
 
CELIX_FRAMEWORK_EXPORT celix_array_list_t*
celix_bundleContext_findServicesWithOptions(celix_bundle_context_t* ctx, const celix_service_filter_options_t* opts);
 
CELIX_FRAMEWORK_DEPRECATED_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));
 
CELIX_FRAMEWORK_DEPRECATED_EXPORT bool celix_bundleContext_useService(
    celix_bundle_context_t *ctx,
    const char* serviceName,
    void *callbackHandle,
    void (*use)(void *handle, void *svc)
);
 
CELIX_FRAMEWORK_DEPRECATED_EXPORT size_t celix_bundleContext_useServices(
    celix_bundle_context_t *ctx,
    const char* serviceName,
    void *callbackHandle,
    void (*use)(void *handle, void *svc)
);
 
typedef struct celix_service_use_options {
    celix_service_filter_options_t filter CELIX_OPTS_INIT;
 
    double waitTimeoutInSeconds CELIX_OPTS_INIT;
 
    void* callbackHandle CELIX_OPTS_INIT;
 
    void (*use)(void* handle, void* svc) CELIX_OPTS_INIT;
 
    void (*useWithProperties)(void* handle, void* svc, const celix_properties_t* props) CELIX_OPTS_INIT;
 
    void (*useWithOwner)(void* handle, void* svc, const celix_properties_t* props, const celix_bundle_t* svcOwner)
        CELIX_OPTS_INIT;
} celix_service_use_options_t;
 
#ifndef __cplusplus
 
#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}
#endif
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useServiceWithOptions(
    celix_bundle_context_t *ctx,
    const celix_service_use_options_t *opts);
 
 
CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useServicesWithOptions(
    celix_bundle_context_t *ctx,
    const celix_service_use_options_t *opts);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServicesAsync(celix_bundle_context_t* ctx,
                                                                   const char* serviceName);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServices(celix_bundle_context_t* ctx, const char* serviceName);
 
typedef struct celix_service_tracking_options {
    celix_service_filter_options_t filter CELIX_OPTS_INIT;
 
    void* callbackHandle CELIX_OPTS_INIT;
 
    void (*set)(void* handle, void* svc) CELIX_OPTS_INIT;
 
    void (*setWithProperties)(void* handle,
                              void* svc,
                              const celix_properties_t* props) CELIX_OPTS_INIT; // highest ranking
 
    void (*setWithOwner)(void* handle, void* svc, const celix_properties_t* props, const celix_bundle_t* svcOwner)
        CELIX_OPTS_INIT;
 
    void (*add)(void* handle, void* svc) CELIX_OPTS_INIT;
 
    void (*addWithProperties)(void* handle, void* svc, const celix_properties_t* props) CELIX_OPTS_INIT;
 
    void (*addWithOwner)(void* handle, void* svc, const celix_properties_t* props, const celix_bundle_t* svcOwner)
        CELIX_OPTS_INIT;
 
    void (*remove)(void* handle, void* svc) CELIX_OPTS_INIT;
 
    void (*removeWithProperties)(void* handle, void* svc, const celix_properties_t* props) CELIX_OPTS_INIT;
 
    void (*removeWithOwner)(void* handle, void* svc, const celix_properties_t* props, const celix_bundle_t* svcOwner)
        CELIX_OPTS_INIT;
 
    void* trackerCreatedCallbackData CELIX_OPTS_INIT;
 
    void (*trackerCreatedCallback)(void* trackerCreatedCallbackData) CELIX_OPTS_INIT;
} celix_service_tracking_options_t;
 
#ifndef __cplusplus
 
#define CELIX_EMPTY_SERVICE_TRACKING_OPTIONS { .filter.serviceName = NULL, \
    .filter.versionRange = NULL, \
    .filter.filter = NULL, \
    .callbackHandle = NULL, \
    .set = NULL, \
    .add = NULL, \
    .remove = NULL, \
    .setWithProperties = NULL, \
    .addWithProperties = NULL, \
    .removeWithProperties = NULL, \
    .setWithOwner = NULL, \
    .addWithOwner = NULL, \
    .removeWithOwner = NULL, \
    .trackerCreatedCallbackData = NULL, \
    .trackerCreatedCallback = NULL }
#endif
 
CELIX_FRAMEWORK_EXPORT long
celix_bundleContext_trackServicesWithOptionsAsync(celix_bundle_context_t* ctx,
                                                  const celix_service_tracking_options_t* opts);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServicesWithOptions(celix_bundle_context_t* ctx,
                                                                         const celix_service_tracking_options_t* opts);
 
CELIX_FRAMEWORK_EXPORT
bool celix_bundleContext_useTrackedService(celix_bundle_context_t* ctx,
                                           long trackerId,
                                           void* callbackHandle,
                                           void (*use)(void* handle, void* svc));
 
CELIX_FRAMEWORK_EXPORT
size_t celix_bundleContext_useTrackedServices(celix_bundle_context_t* ctx,
                                              long trackerId,
                                              void* callbackHandle,
                                              void (*use)(void* handle, void* svc));
 
typedef struct celix_tracked_service_use_options {
    void* callbackHandle CELIX_OPTS_INIT;
 
    void (*use)(void* handle, void* svc) CELIX_OPTS_INIT;
 
    void (*useWithProperties)(void* handle, void* svc, const celix_properties_t* props) CELIX_OPTS_INIT;
 
    void (*useWithOwner)(void* handle, void* svc, const celix_properties_t* props, const celix_bundle_t* svcOwner)
        CELIX_OPTS_INIT;
} celix_tracked_service_use_options_t;
 
#ifndef __cplusplus
 
#define CELIX_EMPTY_TRACKER_SERVICE_USE_OPTIONS                                                                        \
    { .callbackHandle = NULL, .use = NULL, .useWithProperties = NULL, .useWithOwner = NULL }
#endif
 
CELIX_FRAMEWORK_EXPORT
bool celix_bundleContext_useTrackedServiceWithOptions(celix_bundle_context_t* ctx,
                                                      long trackerId,
                                                      const celix_tracked_service_use_options_t* opts);
 
CELIX_FRAMEWORK_EXPORT
size_t celix_bundleContext_useTrackedServicesWithOptions(celix_bundle_context_t* ctx,
                                                         long trackerId,
                                                         const celix_tracked_service_use_options_t* opts);
 
CELIX_FRAMEWORK_EXPORT
size_t celix_bundleContext_getTrackedServiceCount(celix_bundle_context_t *ctx, long trackerId);
 
CELIX_FRAMEWORK_EXPORT
const char* celix_bundleContext_getTrackedServiceName(celix_bundle_context_t *ctx, long trackerId);
 
CELIX_FRAMEWORK_EXPORT
const char* celix_bundleContext_getTrackedServiceFilter(celix_bundle_context_t* ctx, long trackerId);
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_stopTrackerAsync(
        celix_bundle_context_t *ctx,
        long trackerId,
        void *doneCallbackData,
        void (*doneCallback)(void* doneCallbackData));
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncTracker(celix_bundle_context_t *ctx, long trackerId);
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForAsyncStopTracker(celix_bundle_context_t *ctx, long trackerId);
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_stopTracker(celix_bundle_context_t *ctx, long trackerId);
 
CELIX_FRAMEWORK_EXPORT
bool celix_bundleContext_isValidTrackerId(celix_bundle_context_t* ctx, long trackerId);
 
typedef struct celix_tracker_guard {
    celix_bundle_context_t* ctx;
    long trackerId;
} celix_tracker_guard_t;
 
static CELIX_UNUSED inline celix_tracker_guard_t
celix_trackerGuard_init(celix_bundle_context_t* ctx, long trackerId) {
    return (celix_tracker_guard_t) { .ctx = ctx, .trackerId = trackerId };
}
 
static CELIX_UNUSED inline void celix_trackerGuard_deinit(celix_tracker_guard_t* trackerGuard) {
    if (trackerGuard->trackerId >= 0) {
        celix_bundleContext_stopTracker(trackerGuard->ctx, trackerGuard->trackerId);
    }
}
 
CELIX_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(celix_tracker_guard_t, celix_trackerGuard_deinit)
 
 
CELIX_FRAMEWORK_EXPORT celix_array_list_t* celix_bundleContext_listBundles(celix_bundle_context_t *ctx);
 
CELIX_FRAMEWORK_EXPORT celix_array_list_t* celix_bundleContext_listInstalledBundles(celix_bundle_context_t *ctx);
 
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_isBundleInstalled(celix_bundle_context_t *ctx, long bndId);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_isBundleActive(celix_bundle_context_t *ctx, long bndId);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_installBundle(celix_bundle_context_t *ctx, const char* bundleUrl, bool autoStart);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_uninstallBundle(celix_bundle_context_t *ctx, long bndId);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_stopBundle(celix_bundle_context_t *ctx, long bndId);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_startBundle(celix_bundle_context_t *ctx, long bndId);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_updateBundle(celix_bundle_context_t *ctx, long bndId, const char* updatedBundleUrl);
 
CELIX_FRAMEWORK_EXPORT char* celix_bundleContext_getBundleSymbolicName(celix_bundle_context_t *ctx, long bndId);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundlesAsync(
        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)
);
 
CELIX_FRAMEWORK_EXPORT 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)
);
 
typedef struct celix_bundle_tracker_options {
    void* callbackHandle CELIX_OPTS_INIT;
 
    void (*onInstalled)(void *handle, const celix_bundle_t *bundle) CELIX_OPTS_INIT;
 
    void (*onStarted)(void *handle, const celix_bundle_t *bundle) CELIX_OPTS_INIT;
 
    void (*onStopped)(void *handle, const celix_bundle_t *bundle) CELIX_OPTS_INIT;
 
    void (*onBundleEvent)(void *handle, const celix_bundle_event_t *event) CELIX_OPTS_INIT;
 
    bool includeFrameworkBundle CELIX_OPTS_INIT;
 
    void *trackerCreatedCallbackData CELIX_OPTS_INIT;
 
    void (*trackerCreatedCallback)(void *trackerCreatedCallbackData) CELIX_OPTS_INIT;
} celix_bundle_tracking_options_t;
 
#ifndef __cplusplus
 
#define CELIX_EMPTY_BUNDLE_TRACKING_OPTIONS {.callbackHandle = NULL, .onInstalled = NULL, .onStarted = NULL, .onStopped = NULL, .onBundleEvent = NULL, .includeFrameworkBundle = false, .trackerCreatedCallbackData = NULL, .trackerCreatedCallback = NULL}
#endif
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundlesWithOptionsAsync(
        celix_bundle_context_t *ctx,
        const celix_bundle_tracking_options_t *opts
);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackBundlesWithOptions(
        celix_bundle_context_t *ctx,
        const celix_bundle_tracking_options_t *opts
);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_useBundle(
        celix_bundle_context_t *ctx,
        long bundleId,
        void *callbackHandle,
        void (*use)(void *handle, const celix_bundle_t *bundle));
 
CELIX_FRAMEWORK_EXPORT size_t celix_bundleContext_useBundles(
        celix_bundle_context_t *ctx,
        void *callbackHandle,
        void (*use)(void *handle, const celix_bundle_t *bundle));
 
typedef struct celix_service_tracker_info {
    celix_filter_t *filter;
 
    const char* serviceName;
 
    long bundleId;
} celix_service_tracker_info_t;
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_trackServiceTrackersAsync(
        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),
        void *doneCallbackData,
        void (*doneCallback)(void* doneCallbackData));
 
CELIX_FRAMEWORK_EXPORT 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_FRAMEWORK_EXPORT celix_dependency_manager_t* celix_bundleContext_getDependencyManager(celix_bundle_context_t *ctx);
 
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_waitForEvents(celix_bundle_context_t *ctx);
 
typedef struct celix_scheduled_event_options {
    const char* name CELIX_OPTS_INIT; 
    double initialDelayInSeconds CELIX_OPTS_INIT; 
    double intervalInSeconds CELIX_OPTS_INIT; 
    void* callbackData CELIX_OPTS_INIT; 
    void (*callback)(void* callbackData) CELIX_OPTS_INIT; 
    void* removeCallbackData
        CELIX_OPTS_INIT; 
    void (*removeCallback)(void* removeCallbackData)
        CELIX_OPTS_INIT; 
} celix_scheduled_event_options_t;
 
#define CELIX_EMPTY_SCHEDULED_EVENT_OPTIONS {NULL, 0.0, 0.0, NULL, NULL, NULL, NULL}
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_scheduleEvent(celix_bundle_context_t* ctx,
                                                              const celix_scheduled_event_options_t* options);
 
CELIX_FRAMEWORK_EXPORT celix_status_t celix_bundleContext_wakeupScheduledEvent(celix_bundle_context_t* ctx,
                                                                               long scheduledEventId);
 
CELIX_FRAMEWORK_EXPORT celix_status_t celix_bundleContext_waitForScheduledEvent(celix_bundle_context_t* ctx,
                                                                                long scheduledEventId,
                                                                                double waitTimeInSeconds);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_removeScheduledEvent(celix_bundle_context_t* ctx,
                                                                      long scheduledEventId);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_removeScheduledEventAsync(celix_bundle_context_t* ctx,
                                                                     long scheduledEventId);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_tryRemoveScheduledEventAsync(celix_bundle_context_t* ctx,
                                                                        long scheduledEventId);
 
CELIX_FRAMEWORK_EXPORT celix_bundle_t* celix_bundleContext_getBundle(const celix_bundle_context_t *ctx);
 
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_getBundleId(const celix_bundle_context_t *ctx);
 
CELIX_FRAMEWORK_EXPORT celix_framework_t* celix_bundleContext_getFramework(const celix_bundle_context_t *ctx);
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_log(
        const celix_bundle_context_t *ctx,
        celix_log_level_e level,
        const char* format,
        ...) __attribute__((format(printf,3,4)));
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_vlog(
        const celix_bundle_context_t *ctx,
        celix_log_level_e level,
        const char* format,
        va_list formatArgs) __attribute__((format(printf,3,0)));
 
CELIX_FRAMEWORK_EXPORT void celix_bundleContext_logTssErrors(const celix_bundle_context_t* ctx,
                                                             celix_log_level_e level);
 
CELIX_FRAMEWORK_EXPORT const char* celix_bundleContext_getProperty(celix_bundle_context_t *ctx, const char* key, const char* defaultVal);
 
CELIX_FRAMEWORK_EXPORT long celix_bundleContext_getPropertyAsLong(celix_bundle_context_t *ctx, const char* name, long defaultValue);
 
CELIX_FRAMEWORK_EXPORT double celix_bundleContext_getPropertyAsDouble(celix_bundle_context_t *ctx, const char* name, double defaultValue);
 
CELIX_FRAMEWORK_EXPORT bool celix_bundleContext_getPropertyAsBool(celix_bundle_context_t *ctx, const char* name, bool defaultValue);
 
#undef CELIX_OPTS_INIT
 
#ifdef __cplusplus
}
#endif
 
#endif //CELIX_BUNDLE_CONTEXT_H_