![]() |
CTK
0.1.0
The Common Toolkit is a community effort to provide support code for medical image analysis, surgical navigation, and related projects.
|
#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 |
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:
ServiceReferences
from the Framework service registry. 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.
Definition at line 98 of file ctkPluginContext.h.
ctkPluginContext::~ctkPluginContext | ( | ) |
|
protected |
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)".
receiver | The object to connect to. |
slot | The slot to be connected. |
type | The Qt connection type. |
true
if the connection was successfull; false
otherwise. ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
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)".
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. |
true
if the connection was successfull; false
otherwise. ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
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 ctkServiceEvent
s 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
.
receiver | The object to connect to. |
slot | The name of the slot to be connected. |
filter | The filter criteria. |
ctkInvalidArgumentException | If filter contains an invalid filter string that cannot be parsed. |
ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
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.
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. |
ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
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.
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. |
ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
void ctkPluginContext::disconnectServiceListener | ( | QObject * | receiver, |
const char * | slot | ||
) |
Disconnects a slot which has been previously connected with a call to connectServiceListener().
receiver | The object containing the slot. |
slot | The slot to be disconnected. |
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.
filename | A relative name to the file or directory to be accessed. |
QFileInfo
object that represents the requested file or directory. ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
QSharedPointer<ctkPlugin> ctkPluginContext::getPlugin | ( | ) | const |
Returns the ctkPlugin
object associated with this ctkPluginContext
. This plugin is called the context plugin.
ctkPlugin
object associated with this ctkPluginContext
. ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
QSharedPointer<ctkPlugin> ctkPluginContext::getPlugin | ( | long | id | ) | const |
Returns the plugin with the specified identifier.
id | The identifier of the plugin to retrieve. |
ctkPlugin
object or 0
if the identifier does not match any installed plugin. 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.
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.
key | The name of the requested property. |
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:
0
is returned. 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. 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. reference | A reference to the service. |
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. 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). |
|
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
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. 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). |
Definition at line 466 of file ctkPluginContext.h.
|
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.
ctkServiceReference
object, or 0
if no services are registered which implement the named class. ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
ctkServiceException | It no service was registered under the given class name. |
Definition at line 375 of file ctkPluginContext.h.
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.
clazz | The class name with which the service was registered. |
ctkServiceReference
object, or 0
if no services are registered which implement the named class. ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
ctkServiceException | It no service was registered under the given class name. |
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:
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. filter
is not empty, the filter expression must match the service. 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. |
ctkServiceReference
objects or an empty list if no services are registered which satisfy the search. ctkInvalidArgumentException | If the specified filter contains an invalid filter expression that cannot be parsed. |
ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
|
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.
filter | The filter expression or empty for all services. |
ctkServiceReference
objects or an empty list if no services are registered which satisfy the search. ctkInvalidArgumentException | If the specified filter contains an invalid filter expression that cannot be parsed. |
ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
Definition at line 320 of file ctkPluginContext.h.
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.
ctkPlugin
object for the newly or previously installed plugin is returned. Postconditions, no exceptions thrown
getState()
in { INSTALLED
, RESOLVED
}. Postconditions, when an exception is thrown
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. |
ctkPlugin
object of the installed plugin. ctkPluginException | If the I/O device cannot be read or the installation failed. |
ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
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.
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. |
ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
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:
service
is not a ctkServiceFactory
, an ctkInvalidArgumentException
is thrown if service
is not an instance of all the specified class names. ctkDictionary
(which may be omitted): ctkDictionary
will be ignored. ctkServiceRegistration
object for this registration is returned. 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. |
ctkServiceRegistration
object for use by the plugin registering the service to update the service's properties or to unregister the service. ctkInvalidArgumentException | If one of the following is true:
|
ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
|
inline |
Definition at line 241 of file ctkPluginContext.h.
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:
false
is returned. ctkServiceFactory
object, the ctkServiceFactory#ungetService method is called to release the service object for the context plugin. true
is returned. reference | A reference to the service to be released. |
false
if the context plugin's use count for the service is zero or if the service has been unregistered; true
otherwise. ctkIllegalStateException | If this ctkPluginContext is no longer valid. |
ctkInvalidArgumentException | If the specified ctkServiceReference was not created by the same framework instance as this ctkPluginContext . |
|
friend |
Definition at line 729 of file ctkPluginContext.h.
|
friend |
Definition at line 728 of file ctkPluginContext.h.
|
friend |
Definition at line 730 of file ctkPluginContext.h.
|
protected |
Definition at line 734 of file ctkPluginContext.h.