#include <Libs/PluginFramework/ctkPluginContext.h>

Public Member Functions
bool	connectFrameworkListener (const QObject receiver, const char slot, Qt::ConnectionType type=Qt::QueuedConnection)

bool	connectPluginListener (const QObject receiver, const char slot, Qt::ConnectionType type=Qt::QueuedConnection)

void	connectServiceListener (QObject receiver, const char slot, const QString &filter=QString())

void	disconnectFrameworkListener (const QObject receiver, const char slot=0)

void	disconnectPluginListener (const QObject receiver, const char slot=0)

void	disconnectServiceListener (QObject receiver, const char slot)

QFileInfo	getDataFile (const QString &filename)

QSharedPointer< ctkPlugin >	getPlugin () const

QSharedPointer< ctkPlugin >	getPlugin (long id) const

QList< QSharedPointer< ctkPlugin > >	getPlugins () const

QVariant	getProperty (const QString &key) const

QObject *	getService (const ctkServiceReference &reference)

template<class S >
S *	getService (const ctkServiceReference &reference)

template<class S >
ctkServiceReference	getServiceReference ()

ctkServiceReference	getServiceReference (const QString &clazz)

QList< ctkServiceReference >	getServiceReferences (const QString &clazz, const QString &filter=QString())

template<class S >
QList< ctkServiceReference >	getServiceReferences (const QString &filter=QString())

QSharedPointer< ctkPlugin >	installPlugin (const QUrl &location, QIODevice *input=0)

ctkServiceRegistration	registerService (const char clazz, QObject service, const ctkDictionary &properties=ctkDictionary())

ctkServiceRegistration	registerService (const QStringList &clazzes, QObject *service, const ctkDictionary &properties=ctkDictionary())

template<class S >
ctkServiceRegistration	registerService (QObject *service, const ctkDictionary &properties=ctkDictionary())

bool	ungetService (const ctkServiceReference &reference)

	~ctkPluginContext ()

Protected Member Functions
	ctkPluginContext (ctkPluginPrivate *plugin)

Protected Attributes
ctkPluginContextPrivate *const	d_ptr

Friends
class	ctkPlugin

class	ctkPluginFrameworkPrivate

class	ctkPluginPrivate

Detailed Description

A plugin's execution context within the Framework. The context is used to grant access to other methods so that this plugin can interact with the Framework.

ctkPluginContext methods allow a plugin to:

Subscribe to events published by the Framework.
Register service objects with the Framework service registry.
Retrieve ServiceReferences from the Framework service registry.
Get and release service objects for a referenced service.
Install new plugins in the Framework.
Get the list of plugins installed in the Framework.
Get the ctkPlugin object for a plugin.
Create QFile objects for files in a persistent storage area provided for the plugin by the Framework.

A ctkPluginContext object will be created and provided to the plugin associated with this context when it is started using the ctkPluginActivator::start method. The same ctkPluginContext object will be passed to the plugin associated with this context when it is stopped using the ctkPluginActivator::stop method. A ctkPluginContext object is generally for the private use of its associated plugin and is not meant to be shared with other plugins in the plugin environment.

The ctkPlugin object associated with a ctkPluginContext object is called the context plugin.

The ctkPluginContext object is only valid during the execution of its context plugin; that is, during the period from when the context plugin is in the STARTING, STOPPING, and ACTIVE plugin states. If the ctkPluginContext object is used subsequently, a ctkIllegalStateException must be thrown. The ctkPluginContext object must never be reused after its context plugin is stopped.

The Framework is the only entity that can create ctkPluginContext objects and they are only valid within the Framework that created them.

Remarks: This class is thread safe.

Definition at line 98 of file ctkPluginContext.h.

Constructor & Destructor Documentation

◆ ~ctkPluginContext()

ctkPluginContext::~ctkPluginContext ( )

◆ ctkPluginContext()

ctkPluginContext::ctkPluginContext ( ctkPluginPrivate * plugin )

protected

Member Function Documentation

◆ connectFrameworkListener()

bool ctkPluginContext::connectFrameworkListener	(	const QObject *	receiver,
		const char *	slot,
		Qt::ConnectionType	type = `Qt::QueuedConnection`
	)

Connects the specified slot to the context plugin's signal which emits general Framework events. The signature of the slot must be "slotName(ctkPluginFrameworkEvent)".

Parameters

receiver	The object to connect to.
slot	The slot to be connected.
type	The Qt connection type.

Returns: true if the connection was successfull; false otherwise.

Exceptions

ctkIllegalStateException If this ctkPluginContext is no longer valid.

See also: ctkPluginFrameworkEvent; ctkEventBus

◆ connectPluginListener()

bool ctkPluginContext::connectPluginListener	(	const QObject *	receiver,
		const char *	slot,
		Qt::ConnectionType	type = `Qt::QueuedConnection`
	)

Connects the specified slot to the context plugins's signal which is emitted when a plugin has a lifecycle state change. The signature of the slot must be "slotName(ctkPluginEvent)".

Parameters

receiver	The object to connect to.
slot	The slot to be connected.
type	The Qt connection type. Only Qt::DirectConnection, Qt::QueuedConnection, or Qt::BlockingQueuedConnection is allowed.

Returns: true if the connection was successfull; false otherwise.

Exceptions

ctkIllegalStateException If this ctkPluginContext is no longer valid.

See also: ctkPluginEvent; ctkEventBus

◆ connectServiceListener()

void ctkPluginContext::connectServiceListener	(	QObject *	receiver,
		const char *	slot,
		const QString &	filter = `QString()`
	)

Connects the specified slot with the specified filter to the context plugins's signal emitting service events when a service has a lifecycle state change. The signature of the slot must be "slotName(const ctkServiceEvent&)", but only the name of the slot must be provided as the argument. See ctkLDAPSearchFilter for a description of the filter syntax.

If the object to connect to is destroyed, the slot is automatically disconnected. To explicitly disconnect the slot, use disconnectServiceListener().

If the context plugin's list of listeners already contains the same slot for the given receiver, then this method replaces that slot's filter (which may be null) with the specified one (which may be null).

The slot is called if the filter criteria is met. To filter based upon the class of the service, the filter should reference the ctkPluginConstants#OBJECTCLASS property. If filter is null, all services are considered to match the filter.

When using a filter, it is possible that the ctkServiceEvents for the complete lifecycle of a service will not be delivered to the slot. For example, if the filter only matches when the property x has the value 1, the listener will not be called if the service is registered with the property x not set to the value 1. Subsequently, when the service is modified setting property x to the value 1, the filter will match and the slot will be called with a ServiceEvent of type MODIFIED. Thus, the slot will not be called with a ServiceEvent of type REGISTERED.

Parameters

receiver	The object to connect to.
slot	The name of the slot to be connected.
filter	The filter criteria.

Exceptions

ctkInvalidArgumentException	If `filter` contains an invalid filter string that cannot be parsed.
ctkIllegalStateException	If this ctkPluginContext is no longer valid.

See also: ctkServiceEvent; disconnectServiceListener(); ctkEventBus

◆ disconnectFrameworkListener()

void ctkPluginContext::disconnectFrameworkListener	(	const QObject *	receiver,
		const char *	slot = `0`
	)

Disconnects the specified slot from the context plugin.

If slot is not connected to the context plugin, this method does nothing.

Parameters

receiver	The object which has previously connected `slot`.
slot	The Qt slot to be disconnected. If `NULL`, all slots previously connected via connectFrameworkListener are disconnected.

Exceptions

ctkIllegalStateException If this ctkPluginContext is no longer valid.

◆ disconnectPluginListener()

void ctkPluginContext::disconnectPluginListener	(	const QObject *	receiver,
		const char *	slot = `0`
	)

Disconnects the specified slot from the context plugin.

If slot is not connected to the context plugin, this method does nothing.

Parameters

receiver	The object which has previously connected `slot`.
slot	The Qt slot to be disconnected. If `NULL`, all slots previously connected via connectPluginListener are disconnected.

Exceptions

ctkIllegalStateException If this ctkPluginContext is no longer valid.

◆ disconnectServiceListener()

void ctkPluginContext::disconnectServiceListener	(	QObject *	receiver,
		const char *	slot
	)

Disconnects a slot which has been previously connected with a call to connectServiceListener().

Parameters

receiver	The object containing the slot.
slot	The slot to be disconnected.

See also: connectServiceListener()

◆ getDataFile()

QFileInfo ctkPluginContext::getDataFile ( const QString & filename )

Creates a QFileInfo object for a file or directoryin the persistent storage area provided for the plugin by the Framework.

A QFileInfo object for the base directory of the persistent storage area provided for the context plugin by the Framework can be obtained by calling this method with an empty string as filename.

If the permissions are enabled, the Framework will ensure that the plugin has the ctkFilePermission with actions read,write,delete for all files (recursively) in the persistent storage area provided for the context plugin.

Parameters

filename A relative name to the file or directory to be accessed.

Returns: A QFileInfo object that represents the requested file or directory.

Exceptions

ctkIllegalStateException If this ctkPluginContext is no longer valid.

◆ getPlugin() [1/2]

QSharedPointer<ctkPlugin> ctkPluginContext::getPlugin ( ) const

Returns the ctkPlugin object associated with this ctkPluginContext. This plugin is called the context plugin.

Returns: The ctkPlugin object associated with this ctkPluginContext.

Exceptions

ctkIllegalStateException If this ctkPluginContext is no longer valid.

◆ getPlugin() [2/2]

QSharedPointer<ctkPlugin> ctkPluginContext::getPlugin ( long id ) const

Returns the plugin with the specified identifier.

Parameters

id	The identifier of the plugin to retrieve.

Returns: A ctkPlugin object or 0 if the identifier does not match any installed plugin.

◆ getPlugins()

QList<QSharedPointer<ctkPlugin> > ctkPluginContext::getPlugins ( ) const

Returns a list of all installed plugins.

This method returns a list of all plugins installed in the plugin environment at the time of the call to this method. However, since the Framework is a very dynamic environment, plugins can be installed or uninstalled at anytime.

Returns: A QList of ctkPlugin objects, one object per installed plugin.

◆ getProperty()

QVariant ctkPluginContext::getProperty ( const QString & key ) const

Returns the value of the specified property. If the key is not found in the Framework properties, the system properties are then searched. The method returns an invalid QVariant if the property is not found.

Parameters

key	The name of the requested property.

Returns: The value of the requested property, or an invalid QVariant if the property is undefined.

◆ getService() [1/2]

QObject* ctkPluginContext::getService ( const ctkServiceReference & reference )

Returns the service object referenced by the specified ctkServiceReference object.

A plugin's use of a service is tracked by the plugin's use count of that service. Each time a service's service object is returned by getService(const ctkServiceReference&) the context plugin's use count for that service is incremented by one. Each time the service is released by ungetService(const ctkServiceReference&) the context plugin's use count for that service is decremented by one.

When a plugin's use count for a service drops to zero, the plugin should no longer use that service.

This method will always return 0 when the service associated with this reference has been unregistered.

The following steps are required to get the service object:

If the service has been unregistered, 0 is returned.
The context plugin's use count for this service is incremented by one.
If the context plugin's use count for the service is currently one and the service was registered with an object implementing the ctkServiceFactory interface, the ctkServiceFactory::getService method is called to create a service object for the context plugin. This service object is cached by the Framework. While the context plugin's use count for the service is greater than zero, subsequent calls to get the services's service object for the context plugin will return the cached service object.
If the service object returned by the ctkServiceFactory object is not an instance of all the classes named when the service was registered or the ctkServiceFactory object throws an exception, 0 is returned and a Framework event of type ctkPluginFrameworkEvent::PLUGIN_ERROR containing a ctkServiceException describing the error is fired.
The service object for the service is returned.

Parameters

reference A reference to the service.

Returns: A service object for the service associated with reference or 0 if the service is not registered, the service object returned by a ctkServiceFactory does not implement the classes under which it was registered or the ctkServiceFactory threw an exception.

Exceptions

ctkIllegalStateException	If this ctkPluginContext is no longer valid.
ctkInvalidArgumentException	If the specified `ctkServiceReference` was not created by the same framework instance as this `ctkPluginContext` or if it is invalid (default constructed).

See also: ungetService(const ctkServiceReference&); ctkServiceFactory

◆ getService() [2/2]

template<class S >

S* ctkPluginContext::getService ( const ctkServiceReference & reference )

inline

Returns the service object referenced by the specified ctkServiceReference object.

This is a convenience method which is identical to QObject* getService(ctkServiceReference) except that it casts the service object to the supplied template argument type

Returns: A service object for the service associated with reference or 0 if the service is not registered, the service object returned by a ctkServiceFactory does not implement the classes under which it was registered, the ctkServiceFactory threw an exception or the service could not be casted to the desired type.

Exceptions

ctkIllegalStateException	If this ctkPluginContext is no longer valid.
ctkInvalidArgumentException	If the specified `ctkServiceReference` was not created by the same framework instance as this `ctkPluginContext` or if it is invalid (default constructed).

See also: getService(const ctkServiceReference&); ungetService(const ctkServiceReference&); ctkServiceFactory

Definition at line 466 of file ctkPluginContext.h.

◆ getServiceReference() [1/2]

template<class S >

ctkServiceReference ctkPluginContext::getServiceReference ( )

inline

Returns a ctkServiceReference object for a service that implements and was registered under the specified template class argument.

This method is identical to getServiceReference(const QString&) except that the class name for the service object is automatically deduced from the template argument.

Returns: A ctkServiceReference object, or 0 if no services are registered which implement the named class.

Exceptions

ctkIllegalStateException	If this ctkPluginContext is no longer valid.
ctkServiceException	It no service was registered under the given class name.

See also: getServiceReference(const QString&); getServiceReferences(const QString&)

Definition at line 375 of file ctkPluginContext.h.

◆ getServiceReference() [2/2]

ctkServiceReference ctkPluginContext::getServiceReference ( const QString & clazz )

Returns a ctkServiceReference object for a service that implements and was registered under the specified class.

The returned ctkServiceReference object is valid at the time of the call to this method. However as the Framework is a very dynamic environment, services can be modified or unregistered at any time.

This method is the same as calling ctkPluginContext::getServiceReferences(const QString&, const QString&) 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 ctkPluginConstants::SERVICE_RANKING property) is returned.

If there is a tie in ranking, the service with the lowest service ID (as specified in its ctkPluginConstants::SERVICE_ID property); that is, the service that was registered first is returned.

Parameters

clazz The class name with which the service was registered.

Returns: A ctkServiceReference object, or 0 if no services are registered which implement the named class.

Exceptions

ctkIllegalStateException	If this ctkPluginContext is no longer valid.
ctkServiceException	It no service was registered under the given class name.

See also: getServiceReferences(const QString&, const QString&)

◆ getServiceReferences() [1/2]

QList<ctkServiceReference> ctkPluginContext::getServiceReferences	(	const QString &	clazz,
		const QString &	filter = `QString()`
	)

Returns a list of ctkServiceReference objects. 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 which satisfy the filter expression. See ctkLDAPSearchFilter for a description of the filter syntax. If the specified filter is empty, all registered services are considered to match the filter. If the specified filter expression cannot be parsed, an ctkInvalidArgumentException will be thrown with a human readable message where the filter became unparsable.

The result is a list of ctkServiceReference 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's objectClass 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.

Returns: A list of ctkServiceReference objects or an empty list if no services are registered which satisfy the search.

Exceptions

ctkInvalidArgumentException	If the specified `filter` contains an invalid filter expression that cannot be parsed.
ctkIllegalStateException	If this ctkPluginContext is no longer valid.

◆ getServiceReferences() [2/2]

template<class S >

QList<ctkServiceReference> ctkPluginContext::getServiceReferences ( const QString & filter = QString() )

inline

Returns a list of ctkServiceReference objects. The returned list contains services that were registered under the Qt interface id of the template argument S and match the specified filter expression.

This method is identical to getServiceReferences(const QString&, const QString&) except that the class name for the service object is automatically deduced from the template argument.

Parameters

filter The filter expression or empty for all services.

Returns: A list of ctkServiceReference objects or an empty list if no services are registered which satisfy the search.

Exceptions

ctkInvalidArgumentException	If the specified `filter` contains an invalid filter expression that cannot be parsed.
ctkIllegalStateException	If this ctkPluginContext is no longer valid.

See also: getServiceReferences(const QString&, const QString&)

Definition at line 320 of file ctkPluginContext.h.

◆ installPlugin()

QSharedPointer<ctkPlugin> ctkPluginContext::installPlugin	(	const QUrl &	location,
		QIODevice *	input = `0`
	)

Installs a plugin from the specified QIODevice object.

If the specified QIODevice is null, the Framework must create the QIODevice from which to read the plugin by interpreting, in an implementation dependent manner, the specified location.

The specified location identifier will be used as the identity of the plugin. Every installed plugin is uniquely identified by its location identifier which is typically in the form of a URL.

The following steps are required to install a plugin:

If a plugin containing the same location identifier is already installed, the ctkPlugin object for that plugin is returned.
The plugin's content is read from the input stream. If this fails, a ctkPluginException is thrown.
The plugin's associated resources are allocated. The associated resources minimally consist of a unique identifier and a persistent storage area. If this step fails, a ctkPluginException is thrown.
The plugin's state is set to INSTALLED.
A plugin event of type ctkPluginEvent#INSTALLED is fired.
The ctkPlugin object for the newly or previously installed plugin is returned.

Postconditions, no exceptions thrown

getState() in { INSTALLED, RESOLVED }.
Plugin has a unique ID.

Postconditions, when an exception is thrown

Plugin is not installed and no trace of the plugin exists.

Parameters

location	The location identifier of the plugin to install.
input	The `QIODevice` object from which this plugin will be read or `null` to indicate the Framework must create the I/O device from the specified location identifier. The I/O device must always be closed when this method completes, even if an exception is thrown.

Returns: The ctkPlugin object of the installed plugin.

Exceptions

ctkPluginException	If the I/O device cannot be read or the installation failed.
ctkIllegalStateException	If this ctkPluginContext is no longer valid.

◆ registerService() [1/3]

ctkServiceRegistration ctkPluginContext::registerService	(	const char *	clazz,
		QObject *	service,
		const ctkDictionary &	properties = `ctkDictionary()`
	)

Registers the specified service object with the specified properties under the specified class name with the Framework.

This method is otherwise identical to registerService(const QStringList&, QObject*, const ctkDictionary&) and is provided as a convenience when service will only be registered under a single class name. Note that even in this case the value of the service's ctkPluginConstants::OBJECTCLASS property will be a QStringList, rather than just a single string.

Parameters

clazz	The class name under which the service can be located.
service	The service object or a ctkServiceFactory object.
properties	The properties for this service.

Returns: A ctkServiceRegistration object for use by the plugin registering the service to update the service's properties or to unregister the service.

Exceptions

ctkIllegalStateException If this ctkPluginContext is no longer valid.

See also: registerService(const QStringList&, QObject*, const ctkDictionary&)

◆ registerService() [2/3]

ctkServiceRegistration ctkPluginContext::registerService	(	const QStringList &	clazzes,
		QObject *	service,
		const ctkDictionary &	properties = `ctkDictionary()`
	)

Registers the specified service object with the specified properties under the specified class names into the Framework. A ctkServiceRegistration object is returned. The ctkServiceRegistration object is for the private use of the plugin registering the service and should not be shared with other plugins. The registering plugin is defined to be the context plugin. Other plugins can locate the service by using either the getServiceReferences or getServiceReference method.

A plugin can register a service object that implements the ctkServiceFactory interface to have more flexibility in providing service objects to other plugins.

The following steps are required to register a service:

If service is not a ctkServiceFactory, an ctkInvalidArgumentException is thrown if service is not an instance of all the specified class names.
The Framework adds the following service properties to the service properties from the specified ctkDictionary (which may be omitted):
A property named ctkPluginConstants#SERVICE_ID identifying the registration number of the service
A property named ctkPluginConstants#OBJECTCLASS containing all the specified classes.
Properties with these names in the specified ctkDictionary will be ignored.
The service is added to the Framework service registry and may now be used by other plugins.
A service event of type ctkServiceEvent#REGISTERED is fired.
A ctkServiceRegistration object for this registration is returned.

Parameters

clazzes	The class names under which the service can be located. The class names will be stored in the service's properties under the key ctkPluginConstants#OBJECTCLASS.
service	The service object or a `ctkServiceFactory` object.
properties	The properties for this service. The keys in the properties object must all be `QString` objects. See ctkPluginConstants 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 the ctkServiceRegistration::setProperties method must be called. The set of properties may be omitted if the service has no properties.

Returns: A ctkServiceRegistration object for use by the plugin registering the service to update the service's properties or to unregister the service.

Exceptions

ctkInvalidArgumentException	If one of the following is true: `service` is `0`. `service` is not a `ctkServiceFactory` object and is not an instance of all the named classes in `clazzes`. `properties` contains case variants of the same key name.
ctkIllegalStateException	If this ctkPluginContext is no longer valid.

See also: ctkServiceRegistration; ctkServiceFactory

◆ registerService() [3/3]

template<class S >

ctkServiceRegistration ctkPluginContext::registerService	(	QObject *	service,
		const ctkDictionary &	properties = `ctkDictionary()`
	)

inline

Definition at line 241 of file ctkPluginContext.h.

◆ ungetService()

bool ctkPluginContext::ungetService ( const ctkServiceReference & reference )

Releases the service object referenced by the specified ctkServiceReference object. If the context plugin's use count for the service is zero, this method returns false. Otherwise, the context plugins's use count for the service is decremented by one.

The service's service object should no longer be used and all references to it should be destroyed when a bundle's use count for the service drops to zero.

The following steps are required to unget the service object:

If the context plugin's use count for the service is zero or the service has been unregistered, false is returned.
The context plugin's use count for this service is decremented by one.
If the context plugin's use count for the service is currently zero and the service was registered with a ctkServiceFactory object, the ctkServiceFactory#ungetService method is called to release the service object for the context plugin.
true is returned.

Parameters

reference A reference to the service to be released.

Returns: false if the context plugin's use count for the service is zero or if the service has been unregistered; true otherwise.

Exceptions

ctkIllegalStateException	If this ctkPluginContext is no longer valid.
ctkInvalidArgumentException	If the specified `ctkServiceReference` was not created by the same framework instance as this `ctkPluginContext`.

See also: getService; ctkServiceFactory

Friends And Related Function Documentation

◆ ctkPlugin

friend class ctkPlugin

friend

Definition at line 729 of file ctkPluginContext.h.

◆ ctkPluginFrameworkPrivate

friend class ctkPluginFrameworkPrivate

friend

Definition at line 728 of file ctkPluginContext.h.

◆ ctkPluginPrivate

friend class ctkPluginPrivate

friend

Definition at line 730 of file ctkPluginContext.h.

Member Data Documentation

◆ d_ptr

ctkPluginContextPrivate* const ctkPluginContext::d_ptr

protected

Definition at line 734 of file ctkPluginContext.h.

The documentation for this class was generated from the following file:

Libs/PluginFramework/ctkPluginContext.h

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~ctkPluginContext()

◆ ctkPluginContext()

Member Function Documentation

◆ connectFrameworkListener()

◆ connectPluginListener()

◆ connectServiceListener()

◆ disconnectFrameworkListener()

◆ disconnectPluginListener()

◆ disconnectServiceListener()

◆ getDataFile()

◆ getPlugin() [1/2]

◆ getPlugin() [2/2]

◆ getPlugins()

◆ getProperty()

◆ getService() [1/2]

◆ getService() [2/2]

◆ getServiceReference() [1/2]

◆ getServiceReference() [2/2]

◆ getServiceReferences() [1/2]

◆ getServiceReferences() [2/2]

◆ installPlugin()

◆ registerService() [1/3]

◆ registerService() [2/3]

◆ registerService() [3/3]

◆ ungetService()

Friends And Related Function Documentation

◆ ctkPlugin

◆ ctkPluginFrameworkPrivate

◆ ctkPluginPrivate

Member Data Documentation

◆ d_ptr