QContent Class Reference
[QtBaseModule]

Detailed Description

The QContent class represents a content carrying entity in the Qt Extended system, where content includes resources which an end-user may view or manage.

By creating content with a Role of Data using the setRole() method, resources not intended to be directly consumed by the end-user may also be managed.

A QContent object can be either an executable application or a document. Documents include text documents, pictures, pieces of music, and video clips.

An instance of a QContent may, for example, represent any one of the following types of content:

• a stream
• a file
• a temporary file
• a DRM controlled file (possibly encrypted).
• an item in a container, e.g. an archive or DRM multi-part file

The QContent class is responsible for providing access to meta-data about the content contained in a file or stream.

As a system-wide invariant, the backing store is authoritative for information about content available on the device. For example content stored in a DRM file or a stream may not have a logical file on the file-system.

In general applications should use the QContent and QContentSet interface to manage, and search for resources, instead of calling through to the file-system.

The backing store is typically an SQL database, although it could be some other kind of persistent storage.

The static methods install() and uninstall() are used to update records of meta-data in the backing store in response to hardware and software events such as:

• removable storage being removed
• new content arriving via WAP or MMS
• DRM expiry.

To be notified of these events, create a QContentSet object and connect to its QContentSet::changed() signal.

For an example of using QContent to read, write and create documents see the Notes Application tutorial. For other examples using QContent, see the {Tutorial: Content Filtering}{Content Filtering} and Change Listener tutorials.

See also QContentSet and QContentFilter.

Member Type Documentation

enum QContent::ChangeType

This enum specifies the type of change made to a QContent.

See also QContentSet::changed().

enum QContent::DocumentSystemConnection

Identifies how an application is connected to the Qt Extended Document System.

enum QContent::DrmState

This enum specifies the DRM State of this QContent object.

enum QContent::Property

Convenience enumeration that provides some of the more common content properties. All the properties have a key equal to their enumeration name in the default property group none.

enum QContent::Role

This enum specifies the type of document this QContent object appears to be.

typedef QContent::UsageMode

This typedef is deprecated.

UsageMode has been deprecated, use Role instead.

See also QContent::Role.

Member Function Documentation

QContent::QContent ()

Constructs an empty invalid content object.

QContent::QContent ( QContentId id )

Creates a QContent object by fetching the meta-data from the backing store specified by id. This method will be fast if the object has already been referenced by QContent and QContentSet classes loaded in the current process, since internally the results of calls to the backing store are cached.

QContent::QContent ( const QString & fileName, bool store = true )

Create a QContent based on the content contained in the file represented by fileName.

Passing store specifies whether this content object is stored into the backing store database, or only used as a local object.

QContent::QContent ( const QFileInfo & fi, bool store = true )

Create a QContent based on the content contained in the file represented by fi.

Passing store specifies whether this content object is stored into the backing store, or only used as a local object.

QContent::QContent ( const QContent & other )

Create a QContent by copying the other content object.

QContent::~QContent ()   [virtual]

Destroys the content object.

QStringList QContent::categories () const

Returns a list of category IDs for the categories a QContent has been assigned.

See also setCategories().

void QContent::clearErrors ()   [static]

Clear all error flags and errors strings on all QContent objects. Note: this method clears the global error cache for all QContent objects in this process.

QString QContent::comment () const

Returns the comment for this object, typically used on ToolTips For DRM controlled objects this will include a summary of the rights and DRM status

See also setComment().

bool QContent::commit ()

Writes the changes to the QContent object to the backing store. Returns true if successful

When a QContent is committed a notification is sent to all applications which can be listened for on the QtopiaApplication::contentChanged() signal.

bool QContent::commit ( ChangeType & change )   [protected]

This is an overloaded member function, provided for convenience.

Writes the changes to the QContent to the backing store. Returns true if successful and sets change to the type of change committed.

bool QContent::copyContent ( const QContent & from )

Copies the contents of from to this QContent.

Returns true is successful, otherwise false.

bool QContent::copyTo ( const QString & newPath )

Copies the contents of the file and the meta-info from this QContent to newPath.

Returns true is successful, otherwise false.

See also moveTo().

DocumentSystemConnection QContent::documentSystemConnection ()   [static]

Identifies whether the application connects to the Qt Extended Document Server or performs Document System operations locally.

See also setDocumentSystemConnection().

DrmState QContent::drmState () const

Returns a value of the DrmState enumeration indicating whether the content is DRM protected or not.

bool QContent::error () const

Returns true if this QContent object is in an error state. Call the errorString() method to return a text description of the error.

QString QContent::errorString () const

Returns the error string of this object. If error() is false then this method returns an empty string. Use error() instead of checking for an empty error string. The error string is not translated and therefore should not be used in a user interface.

QContentId QContent::execToContent ( const QString & bin )   [static]

Given an application binary name bin return the QContentId of the QContent record for that application. If bin is the fully qualified path of an ordinary file the QContentId of that file will be returned.

If bin does not refer to any application or file in the backing store then an InvalidId will be returned.

Note that binary names are unique across Qtopia.

QString QContent::executableName () const

Returns the name of the name of the application that will be launched if the QContent is executed.

If the QContent is an application this is the name of the binary, if it is a document it is the executable name of the application associated with the document MIME type.

If the content is not an application and there is no associated application associated with its MIME type then a null string will be returned.

See also setExecutableName() and execute().

void QContent::execute () const

Executes the application associated with this QContent.

See also executableName().

void QContent::execute ( const QStringList & args ) const

This is an overloaded member function, provided for convenience.

Executes the application associated with this QContent, with args as arguments.

See also executableName().

QString QContent::file () const

This function is deprecated.

Returns the file name of the file associated with the QContent. If no file is currently associated with the content this will reserve a new file name and so should be called with caution. To determine if there is a file associated with the QContent call fileKnown().

To get the file name with out potentially creating a new file use fileName() instead.

See also setFile(), executableName(), name(), fileName(), and fileKnown().

bool QContent::fileKnown () const

This function is deprecated.

Returns true if the QContent has been assigned a file name. Calling file() when fileKnown() is false will generate a new file and assign its file name to the QContent.

See also file().

QString QContent::fileName () const

Returns the file name of the file backing this content object.

See also setFile(), executableName(), name(), and file().

QIcon QContent::icon () const

Returns the icon for this object. If the object is an application, then it will be the application icon, otherwise it will be a generic icon for the mime-type of the object.

See also setIcon().

QIcon QContent::icon ( QDrmRights::Permission permission ) const

This is an overloaded member function, provided for convenience.

Returns the icon for this object. If the object is an application, then it will be the application icon, otherwise it will be a generic icon for the mime-type of the object.

If the object is a DRM controlled, a key emblem is super-imposed on the icon. If the content does not have current rights for permission the icon is shown grayed out (using the QIcon dynamic routines).

QString QContent::iconName () const

Returns the path to the icon for this file.

See also icon().

QContentId QContent::id () const

Returns the ID of this QContent. If this QContent is not present in the backing store its value will be QContent::InvalidId.

QContentId QContent::install ( const QFileInfo & fi )   [static]

Takes a QFileInfo reference fi to a content object, and installs the meta-data for it in the backing store. The path must be an absolute path and the file must exist. If the file is a .desktop file linking to an application or a document then link target is installed in the database.

If MIME type data is not available, it is determined by file extension, or failing that, the magic number.

If the object is a DRM-controlled file (i.e. it is a .dcf file, or is otherwise shown as DRM controlled) the DRM subsystem is queried for the DRM status.

See also QContentSet::scan().

void QContent::installBatch ( const QList<QFileInfo> & batch )   [static]

Installs a set of files in a batch, committing to the database only once. This achieves a significant performance boost over multiple calls to install.

See also install().

bool QContent::isDocument () const

Returns true if this QContent object represents a document, or false if it represents an application. Convenience function.

See also usageMode().

bool QContent::isNull () const

Returns true if a QContent is uninitialized; returns false otherwise.

bool QContent::isPreloaded () const

Queries the launcher configuration settings and returns true if an application QContent is in the systems PreloadApps list; otherwise returns false.

If the QContent is a document then the return value will indicate if the associated application is preloaded

Preloaded applications are applications that are launched in the background when Qt Extended is started.

bool QContent::isValid ( bool force = false ) const

Returns false if the Content link is invalid or if the backing file is unavailable, either. due to removal of media or deletion of the file.

Note: the parameter force is retained for compatibility, but is ignored.

QDateTime QContent::lastUpdated () const

Returns the value of the last time underlying file was updated.

QString QContent::linkFile () const

This function is deprecated.

Returns the path of the .desktop file the QContent was generated from or an empty string if the QContent was not generated from a .desktop file.

See also setLinkFile(), file(), and linkFileKnown().

bool QContent::linkFileKnown () const

Returns true if the file associated with this QContent object is already known. If false, calling file() will generate a file name.

See also QContent::fileKnown(), QContent::linkFile(), and QContent::file().

bool QContent::load ( QByteArray & data ) const

Read the unformatted contents of the file associated with a QContent into data.

If data is not empty the contents will be overridden.

Returns true if data could be read from the file and false otherwise.

QString QContent::media () const

Returns the root path of the media the content is stored on.

See also setMedia().

QStringList QContent::mimeTypeIcons () const

Returns an icon path for each MIME type an application QContent an open.

The icon list will contain one icon for each MIME type returned by mimeTypes().

See also mimeTypes().

QList<QDrmRights::Permission> QContent::mimeTypePermissions () const

Returns a DRM permission for each MIME type an application QContent can open. The launcher will ensure that a documents opened from the launcher menu have valid rights for their MIME type permission before launching the application.

The permission list will contain one permission for each MIME type returned by mimeTypes().

See also mimeTypes().

QStringList QContent::mimeTypes () const

Returns a list of MIME types that an application QContent can view or edit. If the QContent is not an application this will return an empty list.

See also setMimeTypes().

bool QContent::moveTo ( const QString & newPath )

Moves the contents of the file and the meta-info from this QContent to newPath.

Returns true if the contents is successfully moved, otherwise false.

Note: The id() of the original file will be invalid and should not be used.

See also copyTo() and rename().

QString QContent::name () const

Returns the user-visible name for this content object

See also setName().

QIODevice * QContent::open ( QIODevice::OpenMode mode )

Opens a QIODevice using mode mode.

Returns the QIODevice if successful, otherwise returns 0. It is the caller's responsibility to delete the return value.

QIODevice * QContent::open () const

This is an overloaded member function, provided for convenience.

Opens a read only QIODevice.

Returns the QIODevice if successful, otherwise returns 0. It is the caller's responsibility to delete the return value.

QDrmRights::Permissions QContent::permissions ( bool force = true ) const

Returns all the DRM permissions the content currently has rights for. If force is true the rights will be re-queried. If force is false a cached value might be returned.

QString QContent::property ( const QString & key, const QString & group = QString() ) const

Returns the value of the key property within a property group.

Property groups provide a namespace for keys. Within a group a QContent may only have one value for a key, but a key may be repeated in another group with a different value. If no group is specified then the default group none is assumed.

See also setProperty().

QString QContent::property ( Property key ) const

This is an overloaded member function, provided for convenience.

Returns the value of the key property.

QString QContent::propertyKey ( Property property )   [static]

Returns the string key for a given property.

void QContent::removeFiles ()

Uninstalls a QContent from the database and removes the associated file from the file-system.

void QContent::removeLinkFile ()

This function is deprecated.

Uninstall the .desktop/link file for this object from the database, and remove it from the file-system.

bool QContent::rename ( const QString & name )

Sets the name of the content to name and renames the associated file to match.

Returns true if the file could be renamed and false otherwise.

See also moveTo() and setName().

QDrmRights QContent::rights ( QDrmRights::Permission permission ) const

Returns a QDrmRights representation of any rights for this object for the given permission.

If drmStatus() returns Unprotected, then this method returns a QDrmRights object with valid rights for all permissions. Use drmStatus() != Unprotected to test for unprotected content and permissions() & [permission] to test for a specific permission.

Displaying the play permissions of a QContent:

    void showPlayRights( const QContent &content, QWidget *parent )
    {
        QDrmRights = content.rights( QDrmRights::Play );

        QString title;

        switch( rights.status() )
        {
        case QDrmRights::Invalid:
            title = tr( "Play permissions invalid." );
            break;
        case QDrmRights::Valid:
            title = tr( "Play permissions valid." );
            break;
        case QDrmRights::ValidInFuture:
            title = tr( "Play permissions pending." );
            break;
        }

        QString message = title;

        foreach( QDrmRights::Constraint constraint, rights.constraints() )
        {
            message += '\n' + constraint.name() + ":\t" + constraint.value();

            for( int i = 0; i < constraint.attributeCount(); i++ )
                message += "\n\t" constraint.attributeName( i ) + ":\t" ) + constraint.attributeValue( i );

        }

        QMessageBox::information( parent, title, QString( "<qt>%1</qt>" ).arg( message );
    }

Role QContent::role () const

Returns the document status of the object as per the Role enum. This value does not usually change. The status is used to determine what to display to the user. Data objects make no sense to display to the user, as they cannot be launched or categorized. These files are only of use to the applications which operate on them.

See also setRole().

bool QContent::save ( const QByteArray & data )

Saves data to the file associated with a QContent.

If the QContent is associated with an existing file its contents will be overwritten, otherwise a new file will be created. In order to create a new file the QContent must have valid values of name() and type().

Returns true if all the data is written to the file and false otherwise.

Saving data to a new file:

    bool saveData( const QString &name, const QString &type, const QByteArray &data )
    {
        QContent content;

        content.setName( name );
        content.setType( type );

        if( content.save( data ) )
        {
            content.commit();
            return true;
        }
        else
        {
            return false;
        }
    }

void QContent::setCategories ( const QStringList & categoryList )

Sets the list of category IDs assigned to a QContent to categoryList.

This will overwrite the list of categories already assigned to a QContent, so new categories should be appended to the list returned by categories() to prevent existing categories being lost.

    content.setCategories( content.categories() << newCategoryId );

The categories will not be written to the backing store until commit() is called.

See also categories() and commit().

void QContent::setComment ( const QString & comment )

Sets a string comment for this object.

See also comment().

bool QContent::setDocumentSystemConnection ( DocumentSystemConnection connection )   [static]

Sets the type of connection the application has to the Qt Extended Document System. Returns true if the connection type is set, false otherwise.

Notes:

• The connection type cannot be changed once connected to the Document System.
• Applications with the GuiServer type always have a direct connection.
• This function has no effect before QApplication is constructed.

See also documentSystemConnection() and QTOPIA_SET_DOCUMENT_SYSTEM_CONNECTION().

void QContent::setExecutableName ( const QString & exec )

This function is deprecated.

Sets the executable name property to exec. If the content is not an executable this will change the file name.

The property will not be written to the backing store until commit() is called.

Use setFile() instead.

See also executableName() and setFile().

void QContent::setFile ( const QString & filename )

Sets the file that this content references to filename.

This does not move the contents of the file, to move a file use moveTo() instead.

See also file() and moveTo().

void QContent::setIcon ( const QString & iconpath )

Sets the icons associated with this content to iconpath.

The property will not be written to the backing store until commit() is called.

See also icon() and commit().

void QContent::setLinkFile ( const QString & filename )

This function is deprecated.

Set the link/.desktop file that this content references to filename.

See also linkFile().

bool QContent::setMedia ( const QString & media )

Sets the root path of the media the file is stored on. Once a QContent has been committed to the database the media cannot be changed. Returns true if successful; otherwise false.

See also media().

void QContent::setMimeTypes ( const QStringList & mimeTypes )

Sets the list of MIME types that the application can view or edit to mimeTypes.

The application's icon will be associated with the mime types in document lists and the application will be unable to open DRM protected content from the launcher.

MIME type associations are written to the database when commit() is called, if the QContent is not an application the associations will not be written to the database.

See also mimeTypes().

void QContent::setMimeTypes ( const QStringList & mimeTypes, const QStringList & mimeTypeIcons, const QList<QDrmRights::Permission> & permissions )

This is an overloaded member function, provided for convenience.

Sets the list of MIME types that the application can view or edit to mimeTypes.

The icon displayed each MIME type is obtained from the mimeTypeIcons list, and the DRM permission which is verified for documents opened from the launcher is obtained from the permissions list.

Each mime type is assigned the icon and DRM permission from the corresponding index in the mimeTypeIcons and permissions lists. If there is only one value in either list it is repeated for each MIME type. If a list has more then one item but fewer than mimeTypes then a null value is assigned for the remainder of the MIME types.

MIME type associations are written to the database when commit() is called, if the QContent is not an application the associations will not be written to the database.

See also mimeTypeIcons() and mimeTypePermissions().

void QContent::setName ( const QString & name )

Sets the Name property to name.

The property will not be written to the backing store until commit() is called.

This does not rename the underlying file, to rename a file use rename() instead.

See also name() and rename().

void QContent::setProperty ( const QString & key, const QString & value, const QString & group = QString() )

Sets the key property of a QContent to value. A key is unique within a property group, but may be repeated in another group. If no group is specified then the key is assumed to belong to the default property group none.

The property value will not be written to the backing store until commit() is called.

See also property() and commit().

void QContent::setProperty ( Property key, const QString & value )

This is an overloaded member function, provided for convenience.

Sets the key property of a QContent to value.

The property will not be written to the backing store until commit() is called.

See also commit().

void QContent::setRole ( Role role )

Sets the document status of the object to role as per the Role enum.

See also role().

void QContent::setType ( const QString & type )

Sets the Type property to type.

The property will not be written to the backing store until commit() is called.

See also type() and name().

qint64 QContent::size () const

Returns the plain-text size of the content in bytes

QImage QContent::thumbnail ( const QSize & size = QSize(), Qt::AspectRatioMode mode = Qt::KeepAspectRatio ) const

Returns a representive thumbnail of the content. If size is not null the thumbnail will be resized to fit those dimensions according to the given aspect ratio mode.

QString QContent::type () const

Returns the RFC2045 mime-type for the content.

See also setType().

void QContent::uninstall ( QContentId id )   [static]

Removes the Content with id from the backing store. This does not remove any files associated with the QContent, if the file is in a scanned location it will be reinstalled the next time that location is scanned.

void QContent::uninstallBatch ( const QList<QContentId> & batch )   [static]

Uninstalls a set of files in a batch, committing to the database only once. This achieves a significant performance boost over multiple calls to uninstall().

See also uninstall().

QString QContent::untranslatedName () const

Returns an untranslated user visible name for this content object.

UsageMode QContent::usageMode () const

This function is deprecated.

Returns the document status of the object as per the UsageMode enum. This value does not usually change. The status is used to determine what to display to the user. Data objects make no sense to display to the user, as they cannot be launched or categorized. These files are only of use to the applications which operate on them.

See also role().

QContent & QContent::operator= ( const QContent & other )

Assignment operator. Assigns the data in other to this content object.

bool QContent::operator== ( const QContent & other ) const

Equality operator. Returns true if this QContent object is the same as the other; otherwise returns false.

The values of the QContents are only tested if both are not null and both have invalid IDs, otherwise only the IDs are used to determine equality.

Member Variable Documentation

const QContentId QContent::InvalidId

This variable holds a constant representing an invalid QContent identifier.

Related Non-Members

typedef QContentId

A QContentId is a globally unique identifier for a QContent record. Synonym for QPair<QtopiaDatabaseId, quint64>.

typedef QContentIdList

Synonym for QList<QContentId>.

typedef QtopiaDatabaseId

A QtopiaDatabaseId is a globally unique identifier for a QContent backing store. Synonym for quint32.