Add QMediaBackgroundPlaybackControl interface

Allows some media service backend to provide the ability to can play media in the background while the application is terminated.

Change-Id: Ia5e751367f6d6ea6847c3c873b45df5f971557e2
Reviewed-on: http://codereview.qt.nokia.com/3561
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Michael Goddard <michael.goddard@nokia.com>

5 files changed, 233 insertions, 3 deletions

diff --git a/src/multimediakit/multimediakit.pro b/src/multimediakit/multimediakit.pro
index 8246110ed..f3fdd6880 100644
--- a/src/multimediakit/multimediakit.pro
+++ b/src/multimediakit/multimediakit.pro
@@ -21,6 +21,7 @@ load(qt_module_config)
 
 HEADERS += qtmultimediakitversion.h
 
+
 PRIVATE_HEADERS += \
     qmediacontrol_p.h \
     qmediaobject_p.h \
@@ -44,6 +45,7 @@ PUBLIC_HEADERS += \
     qmediaplaylistnavigator.h \
     qmediaplaylistprovider.h \
     qmediaplaylistioplugin.h \
+    qmediabackgroundplaybackcontrol.h \
     qmediacontent.h \
     qmediaresource.h \
     qmediarecorder.h \
@@ -109,7 +111,8 @@ SOURCES += qmediacontrol.cpp \
     qvideorenderercontrol.cpp \
     qmediatimerange.cpp \
     qmedianetworkaccesscontrol.cpp \
-    qvideosurfaceoutput.cpp
+    qvideosurfaceoutput.cpp \
+    qmediabackgroundplaybackcontrol.cpp
 
 #Camera
 PUBLIC_HEADERS += \
@@ -153,4 +156,3 @@ mac:!qpa {
 }
 
 HEADERS += $$PUBLIC_HEADERS $$PRIVATE_HEADERS
-
diff --git a/src/multimediakit/qmediabackgroundplaybackcontrol.cpp b/src/multimediakit/qmediabackgroundplaybackcontrol.cpp
new file mode 100644
index 000000000..0413fba01
--- /dev/null
+++ b/src/multimediakit/qmediabackgroundplaybackcontrol.cpp
@@ -0,0 +1,149 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** GNU Lesser General Public License Usage
+** This file may be used under the terms of the GNU Lesser General Public
+** License version 2.1 as published by the Free Software Foundation and
+** appearing in the file LICENSE.LGPL included in the packaging of this
+** file. Please review the following information to ensure the GNU Lesser
+** General Public License version 2.1 requirements will be met:
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms and
+** conditions contained in a signed written agreement between you and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qmediabackgroundplaybackcontrol.h"
+#include "qmediacontrol_p.h"
+
+QT_BEGIN_NAMESPACE
+
+
+/*!
+    \class QMediaBackgroundPlaybackControl
+    \inmodule QtMultimediaKit
+    \ingroup multimedia
+    \since 5.0
+
+
+    \brief The QMediaBackgroundPlaybackControl class provides access to the background playback
+    related control of a QMediaService.
+
+    If a QMediaService can play media in background, it should implement QMediaBackgroundPlaybackControl.
+    This control provides a means to set the \l {setContextId()}{contextId} for application,
+    \l {acquire()}{acquire the resource for playback} and \l {release()} {release the playback resource}.
+
+    The interface name of QMediaBackgroundPlaybackControl is \c com.nokia.Qt.QMediaBackgroundPlaybackControl/1.0 as
+    defined in QMediaBackgroundPlaybackControl_iid.
+
+    \sa QMediaService::requestControl(), QMediaPlayer
+*/
+
+/*!
+    \macro QMediaBackgroundPlaybackControl_iid
+
+    \c com.nokia.Qt.QMediaBackgroundPlaybackControl/1.0
+
+    Defines the interface name of the QMediaBackgroundPlaybackControl class.
+
+    \relates QMediaBackgroundPlaybackControl
+*/
+
+/*!
+    Destroys a media background playback control.
+*/
+QMediaBackgroundPlaybackControl::~QMediaBackgroundPlaybackControl()
+{
+}
+
+/*!
+    Constructs a new media background playback control with the given \a parent.
+*/
+QMediaBackgroundPlaybackControl::QMediaBackgroundPlaybackControl(QObject *parent):
+    QMediaControl(*new QMediaControlPrivate, parent)
+{
+}
+
+/*!
+    \fn QMediaBackgroundPlaybackControl::setContextId(const QString& contextId)
+
+    Sets the contextId for the application, the last contextId will be released if previously set.
+    \l {acquire()}{acquire method} will be automatically invoked after setting a new contextId.
+
+    contextId is an unique string set by the application and is used by the background daemon to
+    distinguish and manage different context for different application.
+
+    \since 1.0
+*/
+
+/*!
+    \fn QMediaBackgroundPlaybackControl::acquire()
+
+    Try to acquire the playback resource for current application
+    \since 1.0
+*/
+
+/*!
+    \fn QMediaBackgroundPlaybackControl::release()
+
+    Give up the playback resource if current applicaiton holds it.
+    \since 1.0
+*/
+
+/*!
+    \property QMediaBackgroundPlaybackControl::isAcquired()
+    \brief indicate whether the background playback resource is granted or not
+
+    It may take sometime for the backend to actually update this value before the first use.
+
+    By default this property is false
+
+    \since 1.0
+*/
+
+/*!
+    \fn QMediaBackgroundPlaybackControl::acquired()
+
+    Signals that the playback resource is acquired
+
+    \since 1.0
+*/
+
+/*!
+    \fn QMediaBackgroundPlaybackControl::lost()
+
+    Signals that the playback resource is lost
+
+    \since 1.0
+*/
+
+#include "moc_qmediabackgroundplaybackcontrol.cpp"
+QT_END_NAMESPACE
+
+
diff --git a/src/multimediakit/qmediabackgroundplaybackcontrol.h b/src/multimediakit/qmediabackgroundplaybackcontrol.h
new file mode 100644
index 000000000..1029ba07b
--- /dev/null
+++ b/src/multimediakit/qmediabackgroundplaybackcontrol.h
@@ -0,0 +1,75 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** GNU Lesser General Public License Usage
+** This file may be used under the terms of the GNU Lesser General Public
+** License version 2.1 as published by the Free Software Foundation and
+** appearing in the file LICENSE.LGPL included in the packaging of this
+** file. Please review the following information to ensure the GNU Lesser
+** General Public License version 2.1 requirements will be met:
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms and
+** conditions contained in a signed written agreement between you and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QMEDIABACKGROUNDPLAYBACKCONTROL_H
+#define QMEDIABACKGROUNDPLAYBACKCONTROL_H
+
+#include "qmediacontrol.h"
+
+QT_BEGIN_NAMESPACE
+
+class Q_MULTIMEDIA_EXPORT QMediaBackgroundPlaybackControl : public QMediaControl
+{
+    Q_OBJECT
+
+public:
+    virtual ~QMediaBackgroundPlaybackControl();
+
+    virtual void setContextId(const QString& contextId) = 0;
+    virtual void acquire() = 0;
+    virtual void release() = 0;
+
+    virtual bool isAcquired() const = 0;
+
+Q_SIGNALS:
+    void acquired();
+    void lost();
+
+protected:
+    QMediaBackgroundPlaybackControl(QObject* parent = 0);
+};
+
+#define QMediaBackgroundPlaybackControl_iid "com.nokia.Qt.QMediaBackgroundPlaybackControl/1.0"
+Q_MEDIA_DECLARE_CONTROL(QMediaBackgroundPlaybackControl, QMediaBackgroundPlaybackControl_iid)
+
+QT_END_NAMESPACE
+
+#endif // QMEDIABACKGROUNDPLAYBACKCONTROL_H
diff --git a/src/multimediakit/qmediaserviceprovider.cpp b/src/multimediakit/qmediaserviceprovider.cpp
index dab7fe00d..2341923bf 100644
--- a/src/multimediakit/qmediaserviceprovider.cpp
+++ b/src/multimediakit/qmediaserviceprovider.cpp
@@ -110,6 +110,9 @@ public:
     \value VideoSurface
             The service is capable of renderering to a QAbstractVideoSurface
             output.
+
+    \value BackgroundPlayback
+            The service is capable of doing playback in the background
 */
 
 /*!
diff --git a/src/multimediakit/qmediaserviceprovider.h b/src/multimediakit/qmediaserviceprovider.h
index d9a789bf4..131b67df3 100644
--- a/src/multimediakit/qmediaserviceprovider.h
+++ b/src/multimediakit/qmediaserviceprovider.h
@@ -61,7 +61,8 @@ public:
         LowLatencyPlayback = 0x01,
         RecordingSupport = 0x02,
         StreamPlayback = 0x04,
-        VideoSurface = 0x08
+        VideoSurface = 0x08,
+        BackgroundPlayback = 0x10,
     };
     Q_DECLARE_FLAGS(Features, Feature)