QDrmContent Class Reference
[QtBaseModule]

Detailed Description

The QDrmContent class provides applications with access to DRM protected content.

In order to enforce the constraints placed on DRM protected content it is neccessary to validate the content's permissions before rendering, and to meter usage and revalidate permissions during rendering. QDrmContent provides the interface through which applications can request access to DRM protected content and DRM agents can monitor content usage. An individual QDrmContent object allows access to a single item of content at a time, concurrent access to multiple content items requires a QDrmContent object for each item of content.

File access to DRM content is requested using the the requestLicense() method. If requestLicense() returns true access to the content has been granted and it is possible to access the content using the standard Qt file API. Calling releaseLicense() will relinquish access rights to the content, QDrmContent will automatically release any already held licenses when a new license is requested but a license should be released as soon as possible once done with a file to close access to the file.

To enforce time and use based rights the DRM agent needs to notified of the number of uses and the duration of each use. The renderStarted, renderPaused and renderStopped slots track this information and should be called as appropriate when usage state changes.

QDrmContent will emit a rightsExpired() signal if the rights to the content expires while being rendered. If a DRM protected file is open when this signal is emitted it will remain open, however it will not be possible to reopen the file once it is closed.

An implementation for a simple media player would be:

    class MediaPlayer : public QWidget
    {
    public:
        MediaPlayer( QWidget *parent = 0 );
    public slots:
        bool open( const QContent &content );
        void play();
        void pause();
        void stop();

    signals:
        void playing();
        void paused();
        void stopped();

    private:
        QDrmContent openContent;
    };

    MediaPlayer::MediaPlayer( QWidget *parent = 0 )
        : QWidget( parent )
    {
        openContent.setPermission( QDrmRights::Play );

        // Connect status signals and slots.
        connect( this, SIGNAL(playing()), &openContent, SLOT(renderStarted()));
        connect( this, SIGNAL(paused()), &openContent, SLOT(renderPaused()));
        connect( this, SIGNAL(stopped()), &openContent, SLOT(renderStopped()));

        // Stop playback when the rights have expired.
        connect( &openContent, SIGNAL(rightsExpired(QDrmContent)), this, SLOT(stop()) );

        // Perform initialisation.
    }

    bool MediaPlayer::open( const QContent &content )
    {
        if( openContent.requestLicense( content ) )
        {
            // Open file as normal.

            return true;
        }
        else
            return false;
    }

    void MediaPlayer::close()
    {
        // Close file as normal.

        openContent.releaseLicense();
    }

By default if a license is requested for content without any current rights QDrmContent will prompt the user to activate the content which if successful will result in a license being granted. QDrmContent will also prompt the user to reactivate content which has expired or will in expire in the immediate future when a license for it is released. Both prompts can be disabled by clearing the QDrmContent::Activate and QDrmContent::Reactivate license options respectively.

Member Type Documentation

enum QDrmContent::LicenseOption
flags QDrmContent::LicenseOptions

Specifies options for content licenses.

The LicenseOptions type is a typedef for QFlags<LicenseOption>. It stores an OR combination of LicenseOption values.

enum QDrmContent::RenderState

Represents the current state of a render or usage of content.

Member Function Documentation

QDrmContent::QDrmContent ( QDrmRights::Permission permission = QDrmRights::Unrestricted, LicenseOptions options = Default, QObject * parent = 0 )

Creates a new QDrmContent object for accessing content using the given permission and license options with the parent parent.

QDrmContent::~QDrmContent ()   [virtual]

Destroys a QDrmContent object.

bool QDrmContent::activate ( const QContent & content, QWidget * focus = 0 )   [static]

Initiates an attempt to retrieve rights for the given content.

Returns true if the content has a valid option for activating the content.

Content activation is typically performed asynchronously (i.e. opening a web page where the user may purchase rights.) so rights may not be available until some time after this method is called.

Any dialogs displayed will be parented off the given focus widget.

See also canActivate().

bool QDrmContent::canActivate ( const QContent & content )   [static]

Returns true if options exist to activate the given content; otherwise returns false.

See also activate().

QContent QDrmContent::content () const

Returns the currently licensed QContent.

void QDrmContent::disableLicenseOptions ( LicenseOptions options )

Disables the given license options.

See also licenseOptions(), setLicenseOptions(), and enableLicenseOptions().

void QDrmContent::enableLicenseOptions ( LicenseOptions options )

Enables the given license options.

See also licenseOptions(), setLicenseOptions(), and disableLicenseOptions().

QWidget * QDrmContent::focusWidget () const

Returns the widget that parents any dialogs displayed when activating or reactivating content when requesting and releasing licenses.

See also setFocusWidget().

QList<QPair<QString, QString> > QDrmContent::httpHeaders ()   [static]

Returns a list of HTTP header name/value pairs web applications should use in requests to identify installed DRM agents

void QDrmContent::licenseDenied ( const QContent & content )   [signal]

Signals that a call to QDrmContent::requestLicense() to request a license to render content failed.

See also requestLicense() and licenseGranted().

void QDrmContent::licenseGranted ( const QContent & content )   [signal]

Signals that a call to QDrmContent::requestLicense() to request a license to render content succeeded.

See also requestLicense() and licenseDenied().

LicenseOptions QDrmContent::licenseOptions () const

Returns the license options indicating how the user should be prompted if the content has invalid rights and the type of license that should be requested.

See also setLicenseOptions(), enableLicenseOptions(), and disableLicenseOptions().

QDrmRights::Permission QDrmContent::permission () const

Returns the default permission type or the permission type of the last requested license.

See also setPermission().

void QDrmContent::releaseLicense ()   [slot]

Releases the currently held content license. No further file access will be possible after this unless a new license is requested.

If the permissions have expired or are about to expire the user may be prompted to acquire new permissions, this prompt can be disabled by clearing the Reactivate license option using disableLicenseOptions().

Requesting a new license will automatically release a previously held one.

See also requestLicense().

void QDrmContent::renderPaused ()   [slot]

Notifies the DRM agent that rendering of the content has been paused.

See also renderStarted() and renderStopped().

void QDrmContent::renderStarted ()   [slot]

Notifies the DRM agent that rendering of the content has started.

See also renderStopped() and renderPaused().

RenderState QDrmContent::renderState () const

Returns the current render state.

void QDrmContent::renderStateChanged ( const QDrmContent & content )   [signal]

Signals that the render state of content has changed.

void QDrmContent::renderStopped ()   [slot]

Notifies the DRM agent that rendering of the content has ended.

See also renderStarted() and renderPaused().

bool QDrmContent::requestLicense ( const QContent & content )   [slot]

Requests a license to render DRM content using the currently assigned permission type.

If there are no current permissions to render the content the user will be prompted to acquire new permissions or informed that the content can not be rendered. If the permissions are valid or the user succeeds in acquiring new permissions the licenseGranted() signal will be emitted and true returned. If the permissions are invalid and user cannnot acquire new permissions, or must go through an external agent such as a web browser to acquire new permissions the licenseDenied() signal will be emitted and false returned.

Activatation can be turned off by clearing the Activate license option using disableLicenceOptions().

See also licenseGranted(), licenseDenied(), and permission().

void QDrmContent::rightsExpired ( const QDrmContent & content )   [signal]

Signals that the rights to content have expired.

void QDrmContent::setFocusWidget ( QWidget * widget )

Sets a widget that will parent any dialogs displayed when activating or reactivating content when requesting and releasing licenses.

See also focusWidget().

void QDrmContent::setLicenseOptions ( LicenseOptions options )

Sets the license options indicating how the user should be prompted if the content has invalid rights and the type of license that should be requested.

See also licenseOptions(), enableLicenseOptions(), and disableLicenseOptions().

void QDrmContent::setPermission ( QDrmRights::Permission permission )

Sets the default render permission.

This will only succeed if no license is currently held.

See also permission().

QStringList QDrmContent::supportedTypes ()   [static]

Returns a list of all supported DRM types. Applications should use this list when they need to advertise support for DRM types, for example HTTP accept headers.