summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorWolf Bergenheim <ext-wolf.2.bergenheim@nokia.com>2010-01-27 12:17:38 +0200
committerWolf Bergenheim <ext-wolf.2.bergenheim@nokia.com>2010-01-27 12:17:38 +0200
commit27c45e867533ad43bc2b2e64fe577a503b2d05a8 (patch)
tree37a309e4e726057fdabd3ab681a1294a2fd42e1e
parentca994fc17c8bdb66c64beaead40bc2727ea89468 (diff)
Added library documentation
-rw-r--r--include/resource-set.h133
-rw-r--r--src/resource-set.cpp34
2 files changed, 153 insertions, 14 deletions
diff --git a/include/resource-set.h b/include/resource-set.h
index 193dabc..8d94a44 100644
--- a/include/resource-set.h
+++ b/include/resource-set.h
@@ -7,6 +7,47 @@
#include <QVector>
#include <QList>
+/**
+ * \mainpage Resource Policy Library
+ *
+ * \section intro_section Introduction
+ *
+ * This library is used to request resources from the Polict Resource Manager.
+ * To use this library two classes are provided: \ref ResourcePolicy::Resource and
+ * \ref ResourcePolicy::ResourceSet.
+ *
+ * \section library_use_section Library Usage
+ *
+ * To use the Resource Policy Library, you first need to create a set of
+ * \ref Resource objects like this (given as an example of what a media player
+ * might want/need):
+ * \code
+ * ResourcePolicy::Resource audioResource(AudioPlaybackResource);
+ * ResourcePolicy::Resource videoResource(VideoPlaybackResource);
+ * videoResource.setOptional();
+ * \endcode
+ * Then you need to create a \ref ResourcePolicy::ResourceSet like this:
+ * \code
+ * ResourcePolicy::ResourceSet *resources = new ResourcePolicy::ResourceSet("player");
+ * resources.addResource(audioResource);
+ * resources.addResource(videoResource);
+ * resources->initialize();
+ * QObject::connect(resources, SIGNAL(connectedToManager), this, SLOT(connectedHandler()));
+ * resources->connectToManager();
+ * \endcode
+ * Then the when you want to acquire the \ref ResourcePolicy::ResourceSet you simply use the
+ * \ref acquire() method of the \ref ResourceSet object, like this:
+ * \code
+ * QObject::connect(resources, SIGNAL(resourcesAcquired),
+ * this, SLOT(acquireOkHandler(QList<ResourcePolicy::Resource>)));
+ * QObject::connect(resources, SIGNAL(resourcesDenied), this, SLOT(acquireDeniedHandler()));
+ * resources->acquire();
+ * \endcode
+ */
+
+/**
+ * The Namespace for Resource Policy.
+ */
namespace ResourcePolicy
{
/**
@@ -14,16 +55,6 @@ namespace ResourcePolicy
* a single Resource of a given type. That is one AudioPlaybackResource, etc.
*
* Internally the set is stored as a QVector of \ref Resource objects.
- *
- * \b Examples:
- * This example shows how to create a resourceSet used by a video player
- * \code
- * Resource audioResource(AudioPlaybackResource);
- * Resource videoResource(VideoPlaybackResource);
- * ResourceSet myResourceSet("player");
- * myResourceSet.addResource(audioResource);
- * myResourceSet.addResource(videoResource);
- * \endcode
*/
class ResourceSet: public QObject
{
@@ -35,13 +66,19 @@ namespace ResourcePolicy
* \param applicationClass This parameter defines the application class.
* The application class is used to determine the priority order of the
* application.
+ * \param parent The optional parent of of this class.
*/
- ResourceSet(const QString &applicationClass);
+ ResourceSet(const QString &applicationClass, QObject *parent=NULL);
/**
* The destructor
*/
~ResourceSet();
-
+ /**
+ * Initializes the underlaying communications library.
+ * \return true if initialization is successful.
+ */
+ bool initialize();
+
/**
* This method adds a resource to the set. A set contains only a single
* instance of a given resource. If the ResourceSet already contains a
@@ -67,15 +104,87 @@ namespace ResourcePolicy
*/
QList<Resource> resources();
+ /**
+ * Checks if the \ref ResourceSet contains the given \ref Resource
+ * \param resource The Resource to look for
+ * \return true if the \ref Resource is defined in this \ref ResourceSet
+ */
bool contains(const Resource &resource) const;
+
+ /**
+ * Checks if the \ref ResourceSet contains all given resources.
+ * \param resources A list of resources to check for
+ * \return true if \b all given resources are defined in the ResourceSet.
+ */
bool contains(const QList<Resource> &resources) const;
quint32 id() const;
+
+ /**
+ * Connects to the Resource Policy Manager. The connected() signal is sent
+ * when the connection has been established. Acquiring the ResourceSet can
+ * be attempted at any time after this, but not before.
+ * \return true if the connection request was successfully sent.
+ * \param reconnectOnDisconnect. Set to true to automatically reconnect on
+ * lost connection to the Policy Resource Manager. This optional parameter
+ * defaults to true.
+ */
+ bool connectToManager(bool reconnectOnDisconnect);
+ /**
+ * Disconnects from the Resource Policy Manager. Further attempts at acquiring
+ * the \ref ResourceSet will fail.
+ */
+ void disconnectFromManager();
+ /**
+ * Checks whether the ResourceSet is connected or not.
+ */
+ bool isConnectedToManager();
+ /**
+ * Attempt to acquire the ResourceSet. The response is returned as the
+ * resourcesAcquired() signal.
+ */
+ bool acquire();
+ /**
+ * Release the acquired resources.
+ */
+ bool release();
+ /**
+ * Commit changes to the \ref ResourceSet to the Manager.
+ */
+ bool update();
+
signals:
+ /**
+ * This signal is emited when the Resource Policy Manager notifies that
+ * the given resources have become available.
+ * \param availableResources A list of available resources.
+ */
void resourcesBecameAvailable(QList<Resource> availableResources);
+ /**
+ * This signal is emited as a response to the acquire() request.
+ * \param grantedResources The list of granted resources.
+ */
void resourcesAcquired(QList<Resource> grantedResources);
+ /**
+ * This signal is emited as a response to the acquire() request, in the
+ * case where we are not granted any requests.
+ */
void resourcesDenied();
+ /**
+ * This signal is emited when some other program with a higher priority
+ * superseeds us, and as a result we loose our resources.
+ */
void lostResources();
+ /**
+ * This signal is emited when we have successfully connected to the manager.
+ */
+ void connectedToManager();
+ /**
+ * This signal is emited when we loose the connection to the manager.
+ * A reconnect is automatically attempted.
+ */
+ void disconnectedFromManager();
+
private:
quint32 identifier;
diff --git a/src/resource-set.cpp b/src/resource-set.cpp
index af691b1..8f6431b 100644
--- a/src/resource-set.cpp
+++ b/src/resource-set.cpp
@@ -2,8 +2,9 @@
using namespace ResourcePolicy;
-ResourceSet::ResourceSet(const QString &applicationClass)
- : applicationClass(applicationClass), resourceSet(ResourceGuard)
+ResourceSet::ResourceSet(const QString &applicationClass, QObject * parent)
+ : QObject(parent), applicationClass(applicationClass),
+ resourceSet(ResourceGuard)
{
identifier = (quint32)this;
}
@@ -69,3 +70,32 @@ QList<Resource> ResourceSet::resources()
}
return listOfResources;
}
+
+bool ResourceSet::connectToManager(bool reconnectOnDisconnect)
+{
+ return false;
+}
+
+void ResourceSet::disconnectFromManager()
+{
+}
+
+bool ResourceSet::isConnectedToManager()
+{
+ return false;
+}
+
+bool ResourceSet::acquire()
+{
+ return false;
+}
+
+bool ResourceSet::release()
+{
+ return false;
+}
+
+bool ResourceSet::update()
+{
+ return false;
+}