API documentation

3 files changed, 138 insertions, 9 deletions

diff --git a/include/resource-factory.h b/include/resource-factory.h
index b49a6e8..22de00a 100644
--- a/include/resource-factory.h
+++ b/include/resource-factory.h
@@ -7,15 +7,30 @@
 
 class Resource;
 
+/** This class is a helper class which should be used to create Resources. Note
+ * that it will own all resources, and so should not be deleted before all
+ * resources are ready to be released. The best way to acchieve this is by
+ * makeing the ResourceHandler class own the factory.
+ */
 class ResourceFactory: public QObject
 {
    Q_OBJECT
    Q_DISABLE_COPY( ResourceFactory );
 private:
+   //! \internal
    QDBusConnection sessionBusConnection;
 public:
    ResourceFactory(QObject *parent = 0);
    ~ResourceFactory();
+   /** This method creates a new \ref Resource object.
+    * @param applicationClass The application class to tell the Resource Policy.
+    * @param requestedResources A bit mask of the resources tha this application
+    * wats as a set. If more than one resource is set in this bit mask, then
+    * that set is treated as a whole, and cannot be separated. If the application
+    * needs at times say only audio and at times audio and video, then several
+    * \ref Resource objects need to be created.
+    * @return Returns a pointer to a new Resource, or NULL if there is an error.
+    */
    Resource * createResource(enum ResourceTypes::ResourceClass applicationClass,
 			     quint16 requestedResources=ResourceTypes::AudioResource);
 };
diff --git a/include/resource-types.h b/include/resource-types.h
index 57c6bfc..18f0d4d 100644
--- a/include/resource-types.h
+++ b/include/resource-types.h
@@ -1,8 +1,10 @@
 #ifndef RESOURCE_TYPES_H
 #define RESOURCE_TYPES_H
 
+//! This namespace contains the enumerations used by the Resource library.
 namespace ResourceTypes {
 
+   //! This enum represents the class of the application which uses the resource.
    enum ResourceClass {
 	   InvalidClass = 0,
 	   VoIPClass,
@@ -19,6 +21,8 @@ namespace ResourceTypes {
 	   InputClass
    };
 
+   //! This enum defines the different resources that an application can request.
+   //! \note These are bits and can be combined to a bit mask.
    enum ResourceType {
 	   AudioResource = 0x01,
 	   VideoResource = 0x02,
@@ -26,6 +30,7 @@ namespace ResourceTypes {
 	   VideoRecorderResource = 0x08
    };
 
+   //! The current state of a resource.
    enum ResourceState {
 	   UnknownState,
 	   NotOwnedState,
diff --git a/include/resource.h b/include/resource.h
index 0be0b3a..3399b7c 100644
--- a/include/resource.h
+++ b/include/resource.h
@@ -8,6 +8,53 @@
 
 using namespace ResourceTypes;
 
+/**
+ * This class represents a (set of) requested resource(s). It is created through
+ * the ResourceFactory which knows how to connect it to the underying ResourceLibrary.
+ * This class is responsible for managing the requested resource and is the way
+ * for the application to communicate with the Resource Policy.
+ *
+ * If a program wants to use different sets of resources, e.g. a media player
+ * wanting to play either music or video (audio + video resources), it would then
+ * create multiple resource objects from the ResourceFactory.
+ * 
+ * Here is an example of how a media player might use this class. First off you
+ * are going to need a \ref ResourceFactory which you use to create a \ref Resource.
+ * The Resource has a number of signals, most are not strictly mandatory to connect
+ * to, but in order to have it work correctly you should at least connect to the
+ * connectedToServer() and stateChanged() signals, see this example.
+ * \code
+ *   resourceFactory = new ResourceFactory(this);
+ *   QVERIFY(resourceFactory != NULL);
+ *   Resource *resource = resourceFactory->createResource(MediaClass, AudioResource|VideoResource);
+ *   if(resource == NULL) doError();
+ *   QObject::connect(resource, SIGNAL(connectedToServer()),
+ *                    &myResourceHandler, SLOT(connectedToServer()));
+ *   QObject::connect(resource, SIGNAL(stateChanged(enum ResourceState)),
+ *                    &myResourceHandler, SLOT(stateChanged(enum ResourceState)));
+ *   resource->connectToServer();
+ * \endcode
+ * Then the resource handler would have methods like these to handle the signals:
+ * \code
+ * void MediaPlayerResourceHandler::connectedToServer()
+ * {
+ *     //We are now connected to the Policy Server, we can start requesting.
+ *     this->reserve();
+ * }
+ * 
+ * void MediaPlayerResourceHandler::stateChanged(enum ResourceState)
+ * {
+ *     if(resourceState == ResourceTypes::NotOwnedState) {
+ *         this->mediaStream->stopMedia();
+ *     }
+ *     else if(resourceState == ResourceTypes::NotOwnedState) {
+ *         //We now own the audio and video devices, so we can
+ *         // freely start playing.
+ *         this->mediaStream->startMedia();
+ *     }
+ * }
+ * \endcode
+ */
 class Resource: public QObject
 {
    Q_OBJECT
@@ -15,49 +62,111 @@ class Resource: public QObject
    friend class ResourceFactory;
    friend class TestResource;
 private:
+   //! \internal The Class that the application belongs to.
    enum ResourceClass resourceClass;
+   //! \internal A bit mask of ResourceTypes::ResourceType types which determine the
+   //! the resources which we are interested in.
    quint16 resourceType;
+   //! \internal The ResourceLibrary low-level protocol library wrapper.
    ResourceLibrary *resourceLibrary;
+   //! The current state of the resource, whether we have exclusive access or not.
    enum ResourceState resourceState;
 
+   //! \internal Private Constructor to prevent accidental mis-use
    Resource(enum ResourceClass requestedClass, quint16 requestedResources, QObject *parent=0);
+   //! \internal Initializes the resource library and the low-level protocol library.
    bool initialize(ResourceLibrary *library);
 public:
    virtual ~Resource();
 
-   bool hasExclusiveAccess() const;
+   //! Returns true if we have exclusive access to our resources (as a whole)
+   bool isReserved() const;
+   //! Method used to query whether we have a given resource type in our set.
    bool hasResource(enum ResourceType resourceType) const;
 
+   //! The application class that was registered to this resource.
    enum ResourceClass applicationClass() const;
+   //! Returns the \ref ResourceTypes::ResourceType bit mask of resources.
    quint16 resources() const;
 
+   //! Connects and registeres with the Resource Policy Server. The connectedToServer()
+   //! signal is emited when the connection is successful.
    bool connectToServer();
 
+   //! Disconnects from the Resource Policy server.
+   void disconnectFromServer();
+
+   //! \internal Stores the new state and emits a stateChanged() signal.
    void handleStateChange(enum ResourceState newState);
+   //! \internal Emits the exclusiveAccessIsAvailable() signal.
+   void emitReservable();
+
+   //! Reserve exclusive access to our resources.
+   //! \return true when the message was successfully sent to the server.
+   virtual bool reserve();
+   //! Ask server to relinquish exclusive access to our resources.
+   //! \return true when the message was successfully sent to the server.
+   virtual bool release();
+   //! Query the server of our current state. The stateChanged() signal will
+   //! be emited when the server responds.
+   virtual bool requestState();
 
-   virtual bool requestExclusiveAccess();
-   virtual bool releaseExclusiveAccess();
-   virtual bool getExclusiveAccessState();
-/*
+   //! Set the global Mute state.
    virtual bool setMute();
+   //! unset the global mute state.
    virtual bool unsetMute();
+   //! Query the server for the global mute state. The reply will come
+   //! via the muteState() signal.
    virtual bool requestMute();
-   
+
+   //! Set the global privacy override, i.e. pipe all audio to the public
+   //! audio device (IHF speakers).
    virtual bool setPrivacyOverride();
+   //! Unset the global privacy override, i.e. pipe audio to the private
+   //! headset or eaprpiece if policy dictates so.
    virtual bool unsetPrivacyOverride();
+   //! Query the server for the global provacy override state. The reply
+   //! comes via the privacyOverride() signal.
    virtual bool requestPrivacyOverride();
    
+   //! Set the global bluetooth override, i.e. Do not route audio to the
+   //! bluetooth device even if it is connected.
    virtual bool setBluetoothOverride();
+   //! Unset the global bluetooth override, i.e. audio is routed to a
+   //! connected bluetooth headset if policy dictates so.
    virtual bool unsetBluetoothOverride();
+   //! Query the server for the global bluetooth override flag. The reply
+   //! comes via the bluetoothOverrideState() signal.
    virtual bool requestBluetoothOverride();
 
-   virtual bool setPID(pid_t pid);
+   //! Let the Policy Server know the process ID (PID) of the process which
+   //! will do the actual media playing, in case it differs from the PID
+   //! of the owner of this object.
+   virtual bool setPid(quint32 pid);
+   //! Tell policy the stream name of the media stream that this program uses,
+   //! for the same reasons as above.
    virtual bool setStreamName(const QString & name);
-*/
-   // completed and discarded from libplayback? what are those?
+
 signals:
+   //! Emited when we are connected to the server.
    void connectedToServer();
+   //! Emited when the server notifies us that another process has precedence
+   //! over us. When receiving this signal with the ResourceTypes::NotOwnedState
+   //! the program should immediately stop using the resources it had reserved
+   //! (if it is in use). When receiving this signal with the
+   //! ResourceTypes::OwnedState, it means that we have received access to the
+   //! resources we asked for and are free to start to use them.
    void stateChanged(enum ResourceState newState);
+   //! This is a hint by the Policy Server that our resources are free to use.
+   //! It means we can expect a reserve() to result in a
+   //! stateChanged(ResourceTypes::OwnedState) signal.
+   void reservable();
+   //! This signal shows the global mute state.
+   void muteStateChanged(bool oldMuteState, bool newMuteState);
+   //! This signal shows the global privacy override state.
+   void privacyOverrideChanged(bool PrivacyState, bool newPrivacyState);
+   //! This signal shows the global bluetooth override state.
+   void bluetoothOverrideChanged(bool oldBluetoothState, bool newBluetoothState);
 };
 
 #endif