BundleContext¶
-
class BundleContext¶
A bundle’s execution context within the framework.
The context is used to grant access to other methods so that this bundle can interact with the framework.
BundleContext
methods allow a bundle to:Install other bundles.
Subscribe to events published by the framework.
Register service objects with the framework service registry.
Retrieve
ServiceReference
s from the framework service registry.Get and release service objects for a referenced service.
Get the list of bundles installed in the framework.
Get the
Bundle
object for a bundle.
A
BundleContext
object will be created and provided to the bundle associated with this context when it is started using theBundleActivator::Start
method. The sameBundleContext
object will be passed to the bundle associated with this context when it is stopped using theBundleActivator::Stop
method. ABundleContext
object is generally for the private use of its associated bundle and is not meant to be shared with other bundles in the bundle environment.The
Bundle
object associated with aBundleContext
object is called the context bundle.The
BundleContext
object is only valid during the execution of its context bundle; that is, during the period when the context bundle is started. If theBundleContext
object is used subsequently, astd::runtime_error
is thrown. TheBundleContext
object is never reused after its context bundle is stopped.The framework is the only entity that can create
BundleContext
objects.Remark
This class is thread safe.
Public Functions
-
BundleContext()¶
Constructs an invalid BundleContext object.
Valid bundle context objects can only be created by the framework and are supplied to a bundle via its
BundleActivator
or as a return value of theGetBundleContext()
method.See also
operator bool() const
-
bool operator==(BundleContext const &rhs) const¶
Compares this
BundleContext
object with the specified bundle context.Valid
BundleContext
objects are equal if and only if they represent the same context. InvalidBundleContext
objects are always considered to be equal.- Parameters:
rhs – The
BundleContext
object to compare this object with.- Returns:
true
if thisBundleContext
object is equal torhs
,false
otherwise.
-
bool operator!=(BundleContext const &rhs) const¶
Compares this
BundleContext
object with the specified bundle context for inequality.- Parameters:
rhs – The
BundleContext
object to compare this object with.- Returns:
Returns the result of
!(*this == rhs)
.
-
bool operator<(BundleContext const &rhs) const¶
Compares this
BundleContext
with the specified bundle context for order.How valid BundleContext objects are ordered is an implementation detail and must not be relied on. Invalid
BundleContext
objects will always compare greater then validBundleContext
objects.- Parameters:
rhs – The
BundleContext
object to compare this object with.- Returns:
true
if this object is orderded beforerhs
,false
otherwise.
-
explicit operator bool() const¶
Tests this BundleContext object for validity.
Invalid
BundleContext
objects are created by the default constructor or can be returned by certain framework methods if the context bundle has been uninstalled.A
BundleContext
object can become invalid by assigning anullptr
to it or if the context bundle is stopped.- Returns:
true
if this BundleContext object is valid and can safely be used,false
otherwise.
-
BundleContext &operator=(std::nullptr_t)¶
Releases any resources held or locked by this
BundleContext
and renders it invalid.
-
Any GetProperty(std::string const &key) const¶
Returns the value of the specified property.
If the key is not found in the Framework properties, the method returns an empty
Any
.- Parameters:
key – The name of the requested property.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
- Returns:
The value of the requested property, or an empty
Any
if the property is undefined.
-
AnyMap GetProperties() const¶
Returns all known properties.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
- Returns:
A map of all framework properties.
-
Bundle GetBundle() const¶
Returns the
Bundle
object associated with thisBundleContext
.This bundle is called the context bundle.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
- Returns:
The
Bundle
object associated with thisBundleContext
.
-
Bundle GetBundle(long id) const¶
Returns the bundle with the specified identifier.
- Parameters:
id – The identifier of the bundle to retrieve.
- Throws:
std::logic_error – If the framework instance is not active.
std::runtime_error – If this BundleContext is no longer valid.
- Returns:
A
Bundle
object ornullptr
if the identifier does not match any previously installed bundle.
-
std::vector<Bundle> GetBundles(std::string const &location) const¶
Get the bundles with the specified bundle location.
- Parameters:
location – The location of the bundles to get.
- Throws:
std::logic_error – If the framework instance is not active.
std::runtime_error – If the BundleContext is no longer valid.
- Returns:
The requested {
Bundle}s
or an empty list.
-
std::vector<Bundle> GetBundles() const¶
Returns a list of all known bundles.
This method returns a list of all bundles installed in the bundle environment at the time of the call to this method. This list will also contain bundles which might already have been stopped.
- Throws:
std::runtime_error – If the BundleContext is no longer valid.
- Returns:
A std::vector of
Bundle
objects which will hold one object per known bundle.
-
ServiceRegistrationU RegisterService(InterfaceMapConstPtr const &service, ServiceProperties const &properties = ServiceProperties())¶
Registers the specified service object with the specified properties under the specified class names into the framework.
A
ServiceRegistration
object is returned. TheServiceRegistration
object is for the private use of the bundle registering the service and should not be shared with other bundles. The registering bundle is defined to be the context bundle. Other bundles can locate the service by using either theGetServiceReferences
orGetServiceReference
method.A bundle can register a service object that implements the ServiceFactory or PrototypeServiceFactory interface to have more flexibility in providing service objects to other bundles.
The following steps are taken when registering a service:
The framework adds the following service properties to the service properties from the specified
ServiceProperties
(which may be omitted):
A property named
Constants::SERVICE_IDidentifying the registration number of the service
A property named
Constants::OBJECTCLASScontaining all the specified classes.
A property named
Constants::SERVICE_SCOPEidentifying the scope of the service.
Properties with these names in the specified
ServiceProperties
will be ignored.The service is added to the framework service registry and may now be used by other bundles.
A service event of type ServiceEvent::SERVICE_REGISTERED is fired.
A
ServiceRegistration
object for this registration is returned.
See also
See also
See also
Note
This is a low-level method and should normally not be used directly. Use one of the templated RegisterService methods instead.
- Parameters:
service – A shared_ptr to a map of interface identifiers to service objects.
properties – The properties for this service. The keys in the properties object must all be
std::string
objects. SeeConstants
for a list of standard service property keys. Changes should not be made to this object after calling this method. To update the service’s properties theServiceRegistration::SetProperties
method must be called. The set of properties may be omitted if the service has no properties.
- Throws:
std::runtime_error – If this BundleContext is no longer valid, or if there are case variants of the same key in the supplied properties map.
std::invalid_argument – If the InterfaceMap is empty, or if a service is registered as a null class.
- Returns:
A
ServiceRegistration
object for use by the bundle registering the service to update the service’s properties or to unregister the service. This object cannot be called from a discard-value expression as the intent is for theServiceRegistration
object is intended to be stored by the caller
Registers the specified service object with the specified properties using the specified interfaces types with the framework.
This method is provided as a convenience when registering a service under two interface classes whose type is available to the caller. It is otherwise identical to RegisterService(const InterfaceMap&, const ServiceProperties&) but should be preferred since it avoids errors in the string literal identifying the class name or interface identifier.
Example usage:
class MyService2 : public InterfaceA , public InterfaceB { };
std::shared_ptr<MyService2> myService = std::make_shared<MyService2>(); context.RegisterService<InterfaceA, InterfaceB>(myService);
See also
RegisterService(const InterfaceMap&, const ServiceProperties&)
- Template Parameters:
I1 – The first interface type under which the service can be located.
Interfaces – Additional interface types under which the service can be located.
- Parameters:
impl – A
shared_ptr
to the service objectproperties – The properties for this service.
- Throws:
std::logic_error – If this BundleContext is no longer valid.
ServiceException – If the service type
S
is invalid or theservice
object is nullptr.
- Returns:
A ServiceRegistration object for use by the bundle registering the service to update the service’s properties or to unregister the service.
Registers the specified service factory as a service with the specified properties using the specified template argument as service interface type with the framework.
This method is provided as a convenience when
factory
will only be registered under a single class name whose type is available to the caller. It is otherwise identical to RegisterService(const InterfaceMap&, const ServiceProperties&) but should be preferred since it avoids errors in the string literal identifying the class name or interface identifier.Example usage:
class MyService2 : public InterfaceA , public InterfaceB { };
class MyServiceFactory : public ServiceFactory { virtual InterfaceMapConstPtr GetService(Bundle const& /*bundle*/, ServiceRegistrationBase const& /*registration*/) { return MakeInterfaceMap<InterfaceA, InterfaceB>(std::make_shared<MyService2>()); } virtual void UngetService(Bundle const& /*bundle*/, ServiceRegistrationBase const& /*registration*/, InterfaceMapConstPtr const& /*service*/) { } }; std::shared_ptr<MyServiceFactory> myServiceFactory = std::make_shared<MyServiceFactory>(); context.RegisterService<InterfaceA, InterfaceB>(ToFactory(myServiceFactory));
See also
RegisterService(const InterfaceMap&, const ServiceProperties&)
- Template Parameters:
I1 – The first interface type under which the service can be located.
Interfaces – Additional interface types under which the service can be located.
- Parameters:
factory – A
shared_ptr
to the ServiceFactory object.properties – The properties for this service.
- Throws:
std::logic_error – If this BundleContext is no longer valid.
ServiceException – If the service type
S
is invalid or theservice
factory object is nullptr.
- Returns:
A ServiceRegistration object for use by the bundle registering the service to update the service’s properties or to unregister the service.
-
std::vector<ServiceReferenceU> GetServiceReferences(std::string const &clazz, std::string const &filter = std::string())¶
Returns a list of
ServiceReference
objects ordered by rank.The returned list contains services that were registered under the specified class and match the specified filter expression.
The list is valid at the time of the call to this method. However, since the framework is a very dynamic environment, services can be modified or unregistered at any time.
The specified
filter
expression is used to select the registered services whose service properties contain keys and values that satisfy the filter expression. See LDAPFilter for a description of the filter syntax. If the specifiedfilter
is empty, all registered services are considered to match the filter. If the specifiedfilter
expression cannot be parsed, anstd::invalid_argument
will be thrown with a human-readable message where the filter became unparsable.The result is a list of
ServiceReference
objects for all services that meet all of the following conditions:If the specified class name,
clazz
, is not empty, the service must have been registered with the specified class name. The complete list of class names with which a service was registered is available from the service’sobjectClass
property.If the specified
filter
is not empty, the filter expression must match the service.
- Parameters:
clazz – The class name with which the service was registered or an empty string for all services.
filter – The filter expression or empty for all services.
- Throws:
std::invalid_argument – If the specified
filter
contains an invalid filter expression that cannot be parsed.std::runtime_error – If this BundleContext is no longer valid.
std::logic_error – If the ServiceRegistrationBase object is invalid, or if the service is unregistered.
- Returns:
A list of
ServiceReference
objects or an empty list if no services are registered that satisfy the search. These objects will be in decreasing order of their rank.
-
template<class S>
inline std::vector<ServiceReference<S>> GetServiceReferences(std::string const &filter = std::string())¶ Returns a list of
ServiceReference
objects ordered by rank.The returned list contains services that were registered under the interface id of the template argument
S
and match the specified filter expression.This method is identical to GetServiceReferences(const std::string&, const std::string&) except that the class name for the service object is automatically deduced from the template argument.
- Template Parameters:
S – The type under which the requested service objects must have been registered.
- Parameters:
filter – The filter expression or empty for all services.
- Throws:
std::invalid_argument – If the specified
filter
contains an invalid filter expression that cannot be parsed.std::runtime_error – If this BundleContext is no longer valid.
ServiceException – If the service interface id of
S
is empty, see Service Interface.
- Returns:
A list of
ServiceReference
objects or an empty list if no services are registered which satisfy the search. These objects will be in decreasing order of their rank.
-
ServiceReferenceU GetServiceReference(std::string const &clazz)¶
Returns a
ServiceReference
object for a service that implements and was registered under the specified class.The returned
ServiceReference
object is valid at the time of the call to this method. However as the Micro Services framework is a very dynamic environment, services can be modified or unregistered at any time.This method is the same as calling
BundleContext::GetServiceReferences(const std::string&, const std::string&)
with an empty filter expression. It is provided as a convenience for when the caller is interested in any service that implements the specified class.If multiple such services exist, the service with the highest ranking (as specified in its Constants::SERVICE_RANKING property) is returned.
If there is a tie in ranking, the service with the lowest service ID (as specified in its Constants::SERVICE_ID property); that is, the service that was registered first is returned.
- Parameters:
clazz – The class name with which the service was registered.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
- Returns:
A
ServiceReference
object, or an invalidServiceReference
if no services are registered which implement the named class.
-
template<class S>
inline ServiceReference<S> GetServiceReference()¶ Returns a
ServiceReference
object for a service that implements and was registered under the specified template class argument.This method is identical to GetServiceReference(const std::string&) except that the class name for the service object is automatically deduced from the template argument.
- Template Parameters:
S – The type under which the requested service must have been registered.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
ServiceException – If the service interface id of
S
is empty, see Service Interface.
- Returns:
A
ServiceReference
object, or an invalidServiceReference
if no services are registered which implement the typeS
.
-
std::shared_ptr<void> GetService(ServiceReferenceBase const &reference)¶
Returns the service object referenced by the specified
ServiceReferenceBase
object.A bundle’s use of a service is tracked by the bundle’s use count of that service. Each call to
GetService(const ServiceReference<S>&)
increments the context bundle’s use count by one. The deleter function of the returned shared_ptr object is responsible for decrementing the context bundle’s use count.When a bundle’s use count for a service drops to zero, the bundle should no longer use that service.
This method will always return an empty object when the service associated with this
reference
has been unregistered.The
ServiceObjects
object must be used to obtain multiple service objects for services with prototype scope. For services with singleton or bundle scope, the ServiceObjects::GetService() method behaves the same as the GetService(const ServiceReference<S>&) method. That is, only one, use-counted service object is available from the ServiceObjects object.The following steps are taken to get the service object:
If the service has been unregistered, an empty object is returned.
The context bundle’s use count for this service is incremented by one.
If the context bundle’s use count for the service is currently one and the service was registered with an object implementing the
ServiceFactory
interface, theServiceFactory::GetService
method is called to create a service object for the context bundle. This service object is cached by the framework. While the context bundle’s use count for the service is greater than zero, subsequent calls to get the services’s service object for the context bundle will return the cached service object.
If the
ServiceFactory
object throws an exception, empty object is returned and a warning is logged.A shared_ptr to the service object is returned.
See also
See also
- Parameters:
reference – A reference to the service.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
std::invalid_argument – If the specified
ServiceReferenceBase
is invalid (default constructed).cppmicroservices::SecurityException – if retrieving a service caused a bundle’s shared library to be loaded and the bundle failed a security check.
- Returns:
A shared_ptr to the service object associated with
reference
. An empty shared_ptr is returned if the service is not registered or theServiceFactory
threw an exception
-
InterfaceMapConstPtr GetService(ServiceReferenceU const &reference)¶
Returns the service object referenced by the specified
ServiceReference
object.This is a convenience method which is identical to void* GetService(const ServiceReferenceBase&) except that it casts the service object to the supplied template argument type
See also
- Template Parameters:
S – The type the service object will be cast to.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
std::invalid_argument – If the specified
ServiceReference
is invalid (default constructed).cppmicroservices::SecurityException – if retrieving a service caused a bundle’s shared library to be loaded and the bundle failed a security check.
- Returns:
A shared_ptr to the service object associated with
reference
. An empty object is returned if the service is not registered, theServiceFactory
threw an exception or the service could not be cast to the desired type.
-
template<class S>
inline ServiceObjects<S> GetServiceObjects(ServiceReference<S> const &reference)¶ Returns the ServiceObjects object for the service referenced by the specified ServiceReference object.
The ServiceObjects object can be used to obtain multiple service objects for services with prototype scope. For services with singleton or bundle scope, the ServiceObjects::GetService() method behaves the same as the GetService(const ServiceReference<S>&) method. That is, only one, use-counted service object is available from the ServiceObjects object.
See also
- Template Parameters:
S – Type of Service.
- Parameters:
reference – A reference to the service.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
std::invalid_argument – If the specified ServiceReference is invalid (default constructed or the service has been unregistered)
cppmicroservices::SecurityException – if retrieving a service caused a bundle’s shared library to be loaded and the bundle failed a security check.
- Returns:
A ServiceObjects object for the service associated with the specified reference or an invalid instance if the service is not registered.
-
ListenerToken AddServiceListener(ServiceListener const &listener, std::string const &filter = std::string())¶
Adds the specified
listener
with the specifiedfilter
to the context bundles’s list of listeners.See
LDAPFilter
for a description of the filter syntax. Listeners are notified when a service has a lifecycle state change.The framework takes care of removing all listeners registered by this context bundle’s classes after the bundle is stopped.
The
listener
is called if the filter criteria is met. To filter based upon the class of the service, the filter should reference the Constants::OBJECTCLASS property. Iffilter
is empty, all services are considered to match the filter.When using a
filter
, it is possible that theServiceEvent
s for the complete lifecycle of a service will not be delivered to thelistener
. For example, if thefilter
only matches when the propertyexample_property
has the value1
, thelistener
will not be called if the service is registered with the propertyexample_property
not set to the value1
. Subsequently, when the service is modified setting propertyexample_property
to the value1
, the filter will match and thelistener
will be called with aServiceEvent
of typeSERVICE_MODIFIED
. Thus, thelistener
will not be called with aServiceEvent
of typeSERVICE_REGISTERED
.See also
See also
See also
- Parameters:
listener – Any callable object.
filter – The filter criteria.
- Throws:
std::invalid_argument – If
filter
contains an invalid filter string that cannot be parsed.std::runtime_error – If this BundleContext is no longer valid.
- Returns:
a ListenerToken object which can be used to remove the
listener
from the list of registered listeners.
-
void RemoveServiceListener(ServiceListener const &listener)¶
Removes the specified
listener
from the context bundle’s list of listeners.If the
listener
is not contained in this context bundle’s list of listeners, this method does nothing.Deprecated since version 3.1.0: This function exists only to maintain backwards compatibility and will be removed in the next major release. Use
RemoveListener()
instead.See also
- Parameters:
listener – The callable object to remove.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
-
ListenerToken AddBundleListener(BundleListener const &listener)¶
Adds the specified
listener
to the context bundles’s list of listeners.Listeners are notified when a bundle has a lifecycle state change.
See also
See also
- Parameters:
listener – Any callable object.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
- Returns:
a ListenerToken object which can be used to remove the
listener
from the list of registered listeners.
-
void RemoveBundleListener(BundleListener const &listener)¶
Removes the specified
listener
from the context bundle’s list of listeners.If the
listener
is not contained in this context bundle’s list of listeners, this method does nothing.Deprecated since version 3.1.0: This function exists only to maintain backwards compatibility and will be removed in the next major release. Use
RemoveListener()
instead.See also
See also
- Parameters:
listener – The callable object to remove.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
-
ListenerToken AddFrameworkListener(FrameworkListener const &listener)¶
Adds the specified
listener
to the context bundles’s list of framework listeners.Listeners are notified of framework events.
See also
See also
- Parameters:
listener – Any callable object.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
- Returns:
a ListenerToken object which can be used to remove the
listener
from the list of registered listeners.
-
void RemoveFrameworkListener(FrameworkListener const &listener)¶
Removes the specified
listener
from the context bundle’s list of framework listeners.If the
listener
is not contained in this context bundle’s list of listeners, this method does nothing.Deprecated since version 3.1.0: This function exists only to maintain backwards compatibility and will be removed in the next major release. Use
RemoveListener()
instead.See also
See also
- Parameters:
listener – The callable object to remove.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
-
void RemoveListener(ListenerToken token)¶
Removes the registered listener associated with the
token
If the listener associated with the
token
is not contained in this context bundle’s list of listeners or iftoken
is an invalid token, this method does nothing.The token can correspond to one of Service, Bundle or Framework listeners. Using this function to remove the registered listeners is the recommended approach over using any of the other deprecated functions - Remove{Bundle,Framework,Service}Listener.
See also
See also
See also
- Parameters:
token – is an object of type ListenerToken.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
-
template<class R>
inline ListenerToken AddServiceListener(R *receiver, void (R::* callback)(ServiceEvent const&), std::string const &filter = std::string())¶ Adds the specified
callback
with the specifiedfilter
to the context bundles’s list of listeners.See
LDAPFilter
for a description of the filter syntax. Listeners are notified when a service has a lifecycle state change.You must take care to remove registered listeners before the
receiver
object is destroyed. However, the Micro Services framework takes care of removing all listeners registered by this context bundle’s classes after the bundle is stopped.If the context bundle’s list of listeners already contains a pair
(r,c)
ofreceiver
andcallback
such that(r == receiver && c == callback)
, then this method replaces that callback’s filter (which may be empty) with the specified one (which may be empty).The callback is called if the filter criteria is met. To filter based upon the class of the service, the filter should reference the Constants::OBJECTCLASS property. If
filter
is empty, all services are considered to match the filter.When using a
filter
, it is possible that theServiceEvent
s for the complete lifecycle of a service will not be delivered to the callback. For example, if thefilter
only matches when the propertyexample_property
has the value1
, the callback will not be called if the service is registered with the propertyexample_property
not set to the value1
. Subsequently, when the service is modified setting propertyexample_property
to the value1
, the filter will match and the callback will be called with aServiceEvent
of typeSERVICE_MODIFIED
. Thus, the callback will not be called with aServiceEvent
of typeSERVICE_REGISTERED
.Deprecated since version 3.1.0: This function exists only to maintain backwards compatibility and will be removed in the next major release. Use std::bind to bind the member function and then pass the result to
AddServiceListener(const ServiceListener&)
instead.
See also
See also
- Template Parameters:
R – The type of the receiver (containing the member function to be called)
- Parameters:
receiver – The object to connect to.
callback – The member function pointer to call.
filter – The filter criteria.
- Throws:
std::invalid_argument – If
filter
contains an invalid filter string that cannot be parsed.std::runtime_error – If this BundleContext is no longer valid.
- Returns:
a ListenerToken object which can be used to remove the callable from the registered listeners.
-
template<class R>
inline void RemoveServiceListener(R *receiver, void (R::* callback)(ServiceEvent const&))¶ Removes the specified
callback
from the context bundle’s list of listeners.If the
(receiver,callback)
pair is not contained in this context bundle’s list of listeners, this method does nothing.Deprecated since version 3.1.0: This function exists only to maintain backwards compatibility and will be removed in the next major release. Use
RemoveListener()
instead.See also
- Template Parameters:
R – The type of the receiver (containing the member function to be removed)
- Parameters:
receiver – The object from which to disconnect.
callback – The member function pointer to remove.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
-
template<class R>
inline ListenerToken AddBundleListener(R *receiver, void (R::* callback)(BundleEvent const&))¶ Adds the specified
callback
to the context bundles’s list of listeners.Listeners are notified when a bundle has a lifecycle state change.
If the context bundle’s list of listeners already contains a pair
(r,c)
ofreceiver
andcallback
such that(r == receiver && c == callback)
, then this method does nothing.Deprecated since version 3.1.0: This function exists only to maintain backwards compatibility and will be removed in the next major release. Use std::bind to bind the member function and then pass the result to
AddBundleListener(const BundleListener&)
instead.
See also
- Template Parameters:
R – The type of the receiver (containing the member function to be called)
- Parameters:
receiver – The object to connect to.
callback – The member function pointer to call.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
- Returns:
a ListenerToken object which can be used to remove the callable from the registered listeners.
-
template<class R>
inline void RemoveBundleListener(R *receiver, void (R::* callback)(BundleEvent const&))¶ Removes the specified
callback
from the context bundle’s list of listeners.If the
(receiver,callback)
pair is not contained in this context bundle’s list of listeners, this method does nothing.Deprecated since version 3.1.0: This function exists only to maintain backwards compatibility and will be removed in the next major release. Use
RemoveListener()
instead.See also
- Template Parameters:
R – The type of the receiver (containing the member function to be removed)
- Parameters:
receiver – The object from which to disconnect.
callback – The member function pointer to remove.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
-
template<class R>
inline ListenerToken AddFrameworkListener(R *receiver, void (R::* callback)(FrameworkEvent const&))¶ Adds the specified
callback
to the context bundles’s list of framework listeners.Listeners are notified of framework events.
If the context bundle’s list of listeners already contains a pair
(r,c)
ofreceiver
andcallback
such that(r == receiver && c == callback)
, then this method does nothing.Deprecated since version 3.1.0: This function exists only to maintain backwards compatibility and will be removed in the next major release. Use std::bind to bind the member function and then pass the result to :any:`AddFrameworkListener(const FrameworkListener&)
<cppmicroservices::BundleContext::AddFrameworkListener>` instead.
See also
- Template Parameters:
R – The type of the receiver (containing the member function to be called)
- Parameters:
receiver – The object to connect to.
callback – The member function pointer to call.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
- Returns:
a ListenerToken object which can be used to remove the callable from the registered listeners.
-
template<class R>
inline void RemoveFrameworkListener(R *receiver, void (R::* callback)(FrameworkEvent const&))¶ Removes the specified
callback
from the context bundle’s list of framework listeners.If the
(receiver,callback)
pair is not contained in this context bundle’s list of listeners, this method does nothing.Deprecated since version 3.1.0: This function exists only to maintain backwards compatibility and will be removed in the next major release. Use
RemoveListener()
instead.See also
- Template Parameters:
R – The type of the receiver (containing the member function to be removed)
- Parameters:
receiver – The object from which to disconnect.
callback – The member function pointer to remove.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
-
std::string GetDataFile(std::string const &filename) const¶
Get the absolute path for a file or directory in the persistent storage area provided for the bundle.
The absolute path for the base directory of the persistent storage area provided for the context bundle by the Framework can be obtained by calling this method with an empty string as
filename
.- Parameters:
filename – A relative name to the file or directory to be accessed.
- Throws:
std::runtime_error – If this BundleContext is no longer valid.
std::invalid_argument – If the input param filename is not a valid UTF-8 string.
- Returns:
The absolute path to the persistent storage area for the given file name.
-
std::vector<Bundle> InstallBundles(std::string const &location, cppmicroservices::AnyMap const &bundleManifest = cppmicroservices::AnyMap(cppmicroservices::any_map::UNORDERED_MAP_CASEINSENSITIVE_KEYS))¶
Installs all bundles from the bundle library at the specified location.
The following steps are required to install a bundle:
If a bundle containing the same install location is already installed, the Bundle object for that bundle is returned.
The bundle’s associated resources are allocated. The associated resources minimally consist of a unique identifier and a persistent storage area if the platform has file system support. If this step fails, a std::runtime_error is thrown.
A bundle event of type
BundleEvent::BUNDLE_INSTALLED
is fired.The Bundle object for the newly or previously installed bundle is returned.
Remark
An install location is an absolute path to a shared library or executable file which may contain several bundles, i. e. acts as a bundle library.
Remark
If the bundleManifest is passed in, it is installed. In the event that the injected bundle manifest does NOT match the manifest in the bundle’s file, the behavior of the system is undefined.
Remark
If the provided bundleManifest does not match the manifest embedded in the bundle’s file the behavior of that bundle in CppMicroServices is undefined.
Remark
Example JSON representation of manifest AnyMap:
- Parameters:
location – The location of the bundle library to install.
bundleManifest – OPTIONAL - the manifest of the bundle at “location”. If non-empty this will be used without opening the bundle at “location”. Otherwise, the bundle will be opened and the manifest read from there.
- Throws:
std::runtime_error – If the BundleContext is no longer valid, or if the installation failed.
std::logic_error – If the framework instance is no longer active
std::invalid_argument – If the location is not a valid UTF8 string
- Returns:
The Bundle objects of the installed bundle library.