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