summaryrefslogtreecommitdiff
path: root/include/resource.h
blob: d1c386a0174a7415ab29c586814e1c820fd847a1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
#ifndef RESOURCE_H
#define RESOURCE_H

#include <QObject>
#include <QPointer>
#include "resource-library.h"
#include "resource-types.h"

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
   Q_DISABLE_COPY( Resource );
   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();

   //! 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 reservable() 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();

   //! 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();

   //! 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);

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