MeeGo 1.2 Harmattan Developer Documentation Develop for the Nokia N9

ResourcePolicy::ResourceSet Class Reference

Needed resources must be added to the ResourceSet. More...

Inherits QObject.

Collaboration diagram for ResourcePolicy::ResourceSet:
Collaboration graph
[legend]

List of all members.

Signals

void  resourcesBecameAvailable (const QList< ResourcePolicy::ResourceType > &availableResources)
  This signal is emitted when the Resource Policy Manager notifies that the given non-granted resources.
void  resourcesGranted (const QList< ResourcePolicy::ResourceType > &grantedOptionalResources)
  This signal is emitted as a response to the acquire() request (also for the update() request when already granted and updating a modified resource set).
void  updateOK ()
  This signal is emitted as a response to the update() request if the application did not have resources granted while updating.
void  resourcesDenied ()
  This signal is emitted as a response to the acquire() request, in the case where setAlwaysReply() has been called and or more of the mandatory resources were not available.
void  resourcesReleased ()
  This signal is emitted as a response to the release() request.
void  resourcesReleasedByManager ()
  This signal is emitted when the manager releases the acquired resources, so that you have to re-acquire them again when you wish to use them.
void  lostResources ()
  This signal is emitted when some other application with a higher priority supersedes your application, and as a result you loose all our resources temporarily.
void  errorCallback (quint32, const char *)
  Subscribe to this signal to receive error notifications, particularly security errors.
void  managerIsUp ()
  This signals that the manager has started and is available.

Public Member Functions

  ResourceSet (const QString &applicationClass, QObject *parent, bool alwaysReply, bool autoRelease)
  Alternative constructor with additional parameters for setting alwaysReply and autoRelease.
  ResourceSet (const QString &applicationClass, QObject *parent=NULL)
  Alternative backwards-compatible constructor.
  ~ResourceSet ()
  The destructor.
bool  addResource (ResourceType resourceType)
  This method adds a resource to the set.
void  addResourceObject (Resource *resource)
  This method adds a resource to the set.
void  deleteResource (ResourceType type)
  This method removes the resource of the given type.
QList< Resource * >  resources () const
  This method returns a list of all resource in the set.
Resource resource (ResourceType type) const
  This method returns a const pointer to a resource of a specific type.
bool  contains (ResourceType type) const
  Checks if the ResourceSet contains the given Resource.
bool  isConnectedToManager () const
  Checks if this ResourceSet is connected to the policy manager.
bool  contains (const QList< ResourceType > &types) const
  Checks if the ResourceSet contains all given resources.
quint32  id () const
  Returns the unique identifier of this ResourceSet.
QString  applicationClass ()
  Returns the registered application class (given in the constructor).
bool  initAndConnect ()
  Initializes and connects the ResourceSet.
bool  acquire ()
  Try to acquire the resources in this ResourceSet.
bool  release ()
  Releases the acquired resources.
bool  update ()
  Commits changes to the ResourcePolicy::ResourceSet.
bool  setAutoRelease ()
  Sets the auto-release.
bool  willAutoRelease ()
  Checks whether we have setAutoRelease().
bool  setAlwaysReply ()
  Assures that the resourcesGranted() signal is emitted even if we already have those requested resources granted (i.e.
bool  alwaysGetReply ()
  Checks whether the always-get-reply flag has been set with setAlwaysReply().
bool  hasResourcesGranted ()
  ref\ hasResourcesGranted() returns true if this set has any granted resources.

Detailed Description

Needed resources must be added to the ResourceSet.

Each set can only contain a single Resource of a given type. That is one AudioPlaybackResource, etc.

Internally the set is stored as a QVector of Resource objects.


Constructor & Destructor Documentation

ResourcePolicy::ResourceSet::ResourceSet ( const QString applicationClass,
QObject parent,
bool  alwaysReply,
bool  autoRelease  
)

Alternative constructor with additional parameters for setting alwaysReply and autoRelease.

Parameters:
applicationClass  This parameter defines the application class. The application class is used to determine the priority order of the application.
parent  The parent of this class.
alwaysReply  see setAlwaysReply()
autoRelease  see setAutoRelease()
ResourcePolicy::ResourceSet::ResourceSet ( const QString applicationClass,
QObject parent = NULL  
)

Alternative backwards-compatible constructor.

Parameters:
applicationClass  This parameter defines the application class. The application class is used to determine the priority order of the application.
parent  The optional parent of of this class.

Member Function Documentation

bool ResourcePolicy::ResourceSet::addResource ( ResourceType  resourceType  ) 

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 resource of the given type it will be replaced.

Parameters:
resourceType  The resource to add to the set. A copy of this object is stored in the ResourceSet.
void ResourcePolicy::ResourceSet::addResourceObject ( Resource resource  ) 

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 resource of the given type it will be replaced.

Parameters:
resource  The resource to be added to the set. The ResourcePolicy::ResourseSet takes ownership of the pointer. Do NOT free!
void ResourcePolicy::ResourceSet::deleteResource ( ResourceType  type  ) 

This method removes the resource of the given type.

Parameters:
type  The type of resource to be removed from the set.
QList<Resource*> ResourcePolicy::ResourceSet::resources (  )  const

This method returns a list of all resource in the set.

Returns:
a QList of all resources in the set.
Resource* ResourcePolicy::ResourceSet::resource ( ResourceType  type  )  const

This method returns a const pointer to a resource of a specific type.

Parameters:
type  The type of resource we are interested in.
Returns:
a pointer to the Resource if it is defined NULL otherwise.
bool ResourcePolicy::ResourceSet::contains ( ResourceType  type  )  const

Checks if the ResourceSet contains the given Resource.

Parameters:
type  The Resource to look for
Returns:
true if the Resource is defined in this ResourceSet
bool ResourcePolicy::ResourceSet::isConnectedToManager (  )  const

Checks if this ResourceSet is connected to the policy manager.

Returns:
true if this ResourceSet is connected to the manager.
bool ResourcePolicy::ResourceSet::contains ( const QList< ResourceType > &  types  )  const

Checks if the ResourceSet contains all given resources.

Parameters:
types  A list of resources to check for
Returns:
true if all given resources are defined in the ResourceSet.
quint32 ResourcePolicy::ResourceSet::id (  )  const

Returns the unique identifier of this ResourceSet.

Returns:
the unique identifier of this ResourceSet.
bool ResourcePolicy::ResourceSet::initAndConnect (  ) 

Initializes and connects the ResourceSet.

This method can be used before acquire() if one wants to decrease the delay for the initial acquire() (i.e. if not connected, acquire() will call initAndConnect()). In order to avoid an update() after adding resources, add the resources before calling initAndConnect(), and then call acquire().

Returns:
true if the method succeeds without encountering errors.
bool ResourcePolicy::ResourceSet::acquire (  ) 

Try to acquire the resources in this ResourceSet.

The resourcesGranted() (or resourcesDenied() if setAlwaysReply() has been called) signal will be emitted depending on whether the requested resources could be acquired or not. Note that regardless of whether setAlwaysReply() has been called, you will receive the resourcesGranted() signal when the resources could be acquired for you (this could be a long time), and thus you do not have to re-acquire in this case.

bool ResourcePolicy::ResourceSet::update (  ) 

Commits changes to the ResourcePolicy::ResourceSet.

Remember to call update() after adding and/or removing resources. Note that, if you do not have resources acquired when calling update() then this method only informs the policy manager of which resources you are interested in, and this request is acknowledged with a updateOK() signal (if alwaysReply is on by calling setAlwaysReply()). If you do have resources granted then the application will be acknowledged with a resourcesGranted() or lostResources() signal if you lose the resources (in this case you will receive the resources back when possible).

bool ResourcePolicy::ResourceSet::setAutoRelease (  ) 

Sets the auto-release.

When loosing the resources due to another application with a higher priority preempting us, the default is that we automatically re-gain our resources without having to re-acquire them. However if the AutoRelease is set, the resources are released and we need to re-acquire them when the preempting application has released its resources (i.e. when the resourcesBecameAvailable() signal is received).

This feature is by default disabled.

This flag should be set once only before calling anything else (excluding setAlwaysReply()), and cannot be unset.

bool ResourcePolicy::ResourceSet::willAutoRelease (  ) 

Checks whether we have setAutoRelease().

Returns:
true if auto-release is enabled.
bool ResourcePolicy::ResourceSet::setAlwaysReply (  ) 

Assures that the resourcesGranted() signal is emitted even if we already have those requested resources granted (i.e.

the set does not change). By default this feature is off, and note that in that case you will not receive the ref\ updateOK() nor the resourcesDenied() signal. This flag should be set once only before calling anything else (excluding setAutoRelease()) and cannot be unset.

bool ResourcePolicy::ResourceSet::alwaysGetReply (  ) 

Checks whether the always-get-reply flag has been set with setAlwaysReply().

Returns:
true if we will always get a reply (even if there is no change).
void ResourcePolicy::ResourceSet::resourcesBecameAvailable ( const QList< ResourcePolicy::ResourceType > &  availableResources  )  [signal]

This signal is emitted when the Resource Policy Manager notifies that the given non-granted resources.

Parameters:
availableResources  have become available. These are such resources that the application has shown interest in before.
availableResources  A list of available resources.
void ResourcePolicy::ResourceSet::resourcesGranted ( const QList< ResourcePolicy::ResourceType > &  grantedOptionalResources  )  [signal]

This signal is emitted as a response to the acquire() request (also for the update() request when already granted and updating a modified resource set).

Thus, this signal informs of currently granted resources.

Parameters:
grantedOptionalResources  The list of granted optional resources. All the mandatory resources have also been acquired. Note that this signal is also received after an application with higher priority stopped using the resources that were preempted from you with the lostResources() signal (for this autoRelease must be off, see setAutoRelease() ).
void ResourcePolicy::ResourceSet::updateOK (  )  [signal]

This signal is emitted as a response to the update() request if the application did not have resources granted while updating.

Note that a reply to an update() request may also be resourcesLost() if the update request is denied (i.e. trying to add a mandatory resource that is granted to another application with higher priority).

void ResourcePolicy::ResourceSet::resourcesReleased (  )  [signal]

This signal is emitted as a response to the release() request.

Note that the manager can release as well (i.e. resourcesReleasedByManager()). In that case the application will not receive resources automatically anymore, but has to re-acquire them.

void ResourcePolicy::ResourceSet::resourcesReleasedByManager (  )  [signal]

This signal is emitted when the manager releases the acquired resources, so that you have to re-acquire them again when you wish to use them.

Use this signal to implement permanent playback stopping logic in situations where you do not want playback to continue automatically (in contrast to waiting for resourcesGranted() in order to continue playback after a lostResources() signal emission) after your application's resources are preempted because of some other event. Note that when autoRelease is used, you will not receive the resourcesReleasedByManager() ever, but rather you should interpret the resourcesLost() also as an implicit resourcesReleasedByManager().

void ResourcePolicy::ResourceSet::lostResources (  )  [signal]

This signal is emitted when some other application with a higher priority supersedes your application, and as a result you loose all our resources temporarily.

It is very important to connect to this signal as it is signaling when the acquired resources shouldn't be used. When resourcesGranted() is is emitted then the resources can be used again. Note that, when autoRelease mode is used, this signal also signifies that the resources are lost permanently in the sense that they have to be re-acquired when indicated available by the resourcesBecameAvailable() signal (i.e. they are not granted back automatically when freed by an other application in this case).

void ResourcePolicy::ResourceSet::managerIsUp (  )  [signal]

This signals that the manager has started and is available.

This signal was called connectedToManager() before, but that name is now changed to managerIsUp() as that better describes that the manager has booted.


Copyright (C) 2011 Nokia Corporation.
LGPL This file is part of libresourceqt
MeeGo 1.2 Harmattan API