File indexing completed on 2024-10-27 06:45:35

0001 /*
0002     This file is part of the KContacts framework.
0003     SPDX-FileCopyrightText: 2002 Tobias Koenig <tokoe@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KCONTACTS_SOUND_H
0009 #define KCONTACTS_SOUND_H
0010 
0011 #include "kcontacts_export.h"
0012 #include <QSharedDataPointer>
0013 #include <QString>
0014 
0015 namespace KContacts
0016 {
0017 /** @short Class that holds a Sound clip for a contact.
0018  *
0019  *  The sound can be played doing something like this:
0020  *
0021  *  \code
0022  *    KTempFile tmp;
0023  *    if ( sound.isIntern() ) {
0024  *      tmp.file()->write( sound.data() );
0025  *      tmp.close();
0026  *      KAudioPlayer::play( tmp.name() );
0027  *    } else if( !sound.url().isEmpty() ) {
0028  *      QString tmpFile;
0029  *      if ( !KIO::NetAccess::download( QUrl( themeURL.url() ), tmpFile, 0 ) ) {
0030  *        KMessageBox::error( 0,
0031  *                            KIO::NetAccess::lastErrorString(),
0032  *                            i18n( "Failed to download sound file" ),
0033  *                            KMessageBox::Notify
0034  *                          );
0035  *        return;
0036  *      }
0037  *      KAudioPlayer::play( tmpFile );
0038  *    }
0039  *  \endcode
0040  *
0041  *  Unfortunately, KAudioPlayer::play is ASync, so to delete the temporary file
0042  *  the best you can really do is set a timer.
0043  *
0044  */
0045 class KCONTACTS_EXPORT Sound
0046 {
0047     friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const Sound &);
0048     friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, Sound &);
0049 
0050 public:
0051     /**
0052      * Creates an empty sound object.
0053      */
0054     Sound();
0055 
0056     /**
0057      * Creates a sound object for the given url.
0058      *
0059      * @param url A url that describes the position of the sound file.
0060      */
0061     Sound(const QString &url);
0062 
0063     /**
0064      * Creates a sound object for the given data.
0065      *
0066      * @param data The raw data of the sound.
0067      */
0068     Sound(const QByteArray &data);
0069 
0070     /**
0071      * Copy constructor.
0072      */
0073     Sound(const Sound &other);
0074 
0075     /**
0076      * Destroys the sound object.
0077      */
0078     ~Sound();
0079 
0080     typedef QList<Sound> List;
0081     /**
0082      * Assignment operator.
0083      *
0084      * @param other The sound object to assign to @c this
0085      */
0086     Sound &operator=(const Sound &other);
0087 
0088     /**
0089      * Equality operator.
0090      *
0091      * @param other The object to compare with
0092      *
0093      * @return @c true if the two objects are equal, otherwise @c false
0094      */
0095     Q_REQUIRED_RESULT bool operator==(const Sound &other) const;
0096 
0097     /**
0098      * Not-Equal operator.
0099      *
0100      * @param other The object to compare with
0101      *
0102      * @return @c true if the two objects are not equal, otherwise @c false
0103      */
0104     Q_REQUIRED_RESULT bool operator!=(const Sound &other) const;
0105 
0106     /**
0107      * Sets a URL for the location of the sound file. When using this
0108      * function, isIntern() will return 'false' until you use
0109      * setData().
0110      *
0111      * @param url  The location URL of the sound file.
0112      */
0113     void setUrl(const QString &url);
0114 
0115     /**
0116      * Returns true, if the sound object is empty.
0117      */
0118     Q_REQUIRED_RESULT bool isEmpty() const;
0119 
0120     /**
0121      * Sets the raw data of the sound. When using this function,
0122      * isIntern() will return 'true' until you use setUrl().
0123      *
0124      * @param data  The raw data of the sound.
0125      */
0126     void setData(const QByteArray &data);
0127 
0128     /**
0129      * Returns whether the sound is described by a URL (extern) or
0130      * by the raw data (intern).
0131      * When this method returns 'true' you can use data() to
0132      * get the raw data. Otherwise you can request the URL of this
0133      * sound by url() and load the raw data from that location.
0134      */
0135     Q_REQUIRED_RESULT bool isIntern() const;
0136 
0137     /**
0138      * Returns the location URL of this sound.
0139      */
0140     Q_REQUIRED_RESULT QString url() const;
0141 
0142     /**
0143      * Returns the raw data of this sound.
0144      */
0145     Q_REQUIRED_RESULT QByteArray data() const;
0146 
0147     /**
0148      * Returns string representation of the sound.
0149      */
0150     Q_REQUIRED_RESULT QString toString() const;
0151 
0152 private:
0153     class Private;
0154     QSharedDataPointer<Private> d;
0155 };
0156 
0157 /**
0158  * Serializes the @p sound object into the @p stream.
0159  */
0160 KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Sound &sound);
0161 
0162 /**
0163  * Initializes the @p sound object from the @p stream.
0164  */
0165 KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Sound &sound);
0166 }
0167 Q_DECLARE_TYPEINFO(KContacts::Sound, Q_RELOCATABLE_TYPE);
0168 #endif