ctkPluginContext Class Reference

#include <Libs/PluginFramework/ctkPluginContext.h>

Collaboration diagram for ctkPluginContext:
Collaboration graph
[legend]

List of all members.

Public Member Functions

bool connectFrameworkListener (const QObject *receiver, const char *method, Qt::ConnectionType type=Qt::QueuedConnection)
bool connectPluginListener (const QObject *receiver, const char *method, Qt::ConnectionType type=Qt::QueuedConnection)
ctkPlugingetPlugin (long id) const
ctkPlugingetPlugin () const
QList< ctkPlugin * > getPlugins () const
QObject * getService (ctkServiceReference *reference)
ctkServiceReferencegetServiceReference (const QString &clazz)
QList< ctkServiceReference * > getServiceReferences (const QString &clazz, const QString &filter=QString())
ctkPlugininstallPlugin (const QUrl &location, QIODevice *in=0)
ctkServiceRegistrationregisterService (const QStringList &clazzes, QObject *service, const ServiceProperties &properties=ServiceProperties())
 ~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:

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 std::logic_error 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 94 of file ctkPluginContext.h.


Constructor & Destructor Documentation

ctkPluginContext::~ctkPluginContext (  ) 

Definition at line 66 of file ctkPluginContext.cpp.

ctkPluginContext::ctkPluginContext ( ctkPluginPrivate plugin  )  [protected]

Definition at line 62 of file ctkPluginContext.cpp.


Member Function Documentation

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

Definition at line 140 of file ctkPluginContext.cpp.

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

Definition at line 132 of file ctkPluginContext.cpp.

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.

Definition at line 79 of file ctkPluginContext.cpp.

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:
std::logic_error If this ctkPluginContext is no longer valid.

Definition at line 72 of file ctkPluginContext.cpp.

QList< 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.

Definition at line 85 of file ctkPluginContext.cpp.

QObject * ctkPluginContext::getService ( 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(ctkServiceReference*) the context plugin's use count for that service is incremented by one. Each time the service is released by ungetService(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:

  1. If the service has been unregistered, 0 is returned.
  2. The context plugin's use count for this service is incremented by one.
  3. 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(ctkPlugin*, ctkServiceRegistration*) 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 FrameworkEvent::ERROR containing a ctkServiceException describing the error is fired.
  4. 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:
std::logic_error If this ctkPluginContext is no longer valid.
std::invalid_argument If the specified ctkServiceReference was not created by the same framework instance as this ctkPluginContext.
See also:
ungetService(ctkServiceReference*)
ctkServiceFactory

Definition at line 120 of file ctkPluginContext.cpp.

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 PluginConstants::SERVICE_RANKING property) is returned.

If there is a tie in ranking, the service with the lowest service ID (as specified in its PluginConstants::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:
std::logic_error If this ctkPluginContext is no longer valid.
See also:
getServiceReferences(const QString&, const QString&)

Definition at line 113 of file ctkPluginContext.cpp.

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 Filter 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 std::invalid_argument 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:
std::invalid_argument If the specified filter contains an invalid filter expression that cannot be parsed.
std::logic_error If this ctkPluginContext is no longer valid.

Definition at line 106 of file ctkPluginContext.cpp.

ctkPlugin * ctkPluginContext::installPlugin ( const QUrl &  location,
QIODevice *  in = 0 
)

Definition at line 92 of file ctkPluginContext.cpp.

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

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:

  1. If service is not a ctkServiceFactory, an std::invalid_argument is thrown if service is not an instance of all the specified class names.
  2. The Framework adds the following service properties to the service properties from the specified ServiceProperties (which may be omitted):
    A property named PluginConstants#SERVICE_ID identifying the registration number of the service
    A property named PluginConstants#OBJECTCLASS containing all the specified classes.
    Properties with these names in the specified ServiceProperties will be ignored.
  3. The service is added to the Framework service registry and may now be used by other plugins.
  4. A service event of type ServiceEvent#REGISTERED is fired.
  5. 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 PluginConstants#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 PluginConstants 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:
std::invalid_argument 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.
std::logic_error If this ctkPluginContext is no longer valid.
See also:
ctkServiceRegistration
ctkServiceFactory

Definition at line 99 of file ctkPluginContext.cpp.


Friends And Related Function Documentation

friend class ctkPlugin [friend]

Definition at line 350 of file ctkPluginContext.h.

friend class ctkPluginFrameworkPrivate [friend]

Definition at line 349 of file ctkPluginContext.h.

friend class ctkPluginPrivate [friend]

Definition at line 351 of file ctkPluginContext.h.


Member Data Documentation

Definition at line 355 of file ctkPluginContext.h.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Defines

Generated on 21 May 2010 for CTK by  doxygen 1.6.1