1/*
2 This file is part of the KContacts framework.
3 SPDX-FileCopyrightText: 2002 Tobias Koenig <tokoe@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KCONTACTS_SOUND_H
9#define KCONTACTS_SOUND_H
10
11#include "kcontacts_export.h"
12#include <QSharedDataPointer>
13#include <QString>
14
15namespace KContacts
16{
17/*!
18 * \class KContacts::Sound
19 * \inheaderfile KContacts/Sound
20 * \inmodule KContacts
21 *
22 * \brief Class that holds a Sound clip for a contact.
23 *
24 * The sound can be played doing something like this:
25 *
26 * \code
27 * KTempFile tmp;
28 * if ( sound.isIntern() ) {
29 * tmp.file()->write( sound.data() );
30 * tmp.close();
31 * KAudioPlayer::play( tmp.name() );
32 * } else if( !sound.url().isEmpty() ) {
33 * QString tmpFile;
34 * if ( !KIO::NetAccess::download( QUrl( themeURL.url() ), tmpFile, 0 ) ) {
35 * KMessageBox::error( 0,
36 * KIO::NetAccess::lastErrorString(),
37 * i18n( "Failed to download sound file" ),
38 * KMessageBox::Notify
39 * );
40 * return;
41 * }
42 * KAudioPlayer::play( tmpFile );
43 * }
44 * \endcode
45 *
46 * Unfortunately, KAudioPlayer::play is ASync, so to delete the temporary file
47 * the best you can really do is set a timer.
48 */
49class KCONTACTS_EXPORT Sound
50{
51 friend KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &, const Sound &);
52 friend KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &, Sound &);
53
54public:
55 /*!
56 * Creates an empty sound object.
57 */
58 Sound();
59
60 /*!
61 * Creates a sound object for the given url.
62 *
63 * \a url A url that describes the position of the sound file.
64 */
65 Sound(const QString &url);
66
67 /*!
68 * Creates a sound object for the given data.
69 *
70 * \a data The raw data of the sound.
71 */
72 Sound(const QByteArray &data);
73
74 Sound(const Sound &other);
75
76 ~Sound();
77
78 /*!
79 */
80 typedef QList<Sound> List;
81
82 /*!
83 * Assignment operator.
84 *
85 * \a other The sound object to assign to \c this
86 */
87 Sound &operator=(const Sound &other);
88
89 /*!
90 * Equality operator.
91 *
92 * \a other The object to compare with
93 *
94 * Returns \c true if the two objects are equal, otherwise \c false
95 */
96 Q_REQUIRED_RESULT bool operator==(const Sound &other) const;
97
98 /*!
99 * Not-Equal operator.
100 *
101 * \a other The object to compare with
102 *
103 * Returns \c true if the two objects are not equal, otherwise \c false
104 */
105 Q_REQUIRED_RESULT bool operator!=(const Sound &other) const;
106
107 /*!
108 * Sets a URL for the location of the sound file. When using this
109 * function, isIntern() will return \c false until you use
110 * setData().
111 *
112 * \a url The location URL of the sound file.
113 */
114 void setUrl(const QString &url);
115
116 /*!
117 * Returns true, if the sound object is empty.
118 */
119 Q_REQUIRED_RESULT bool isEmpty() const;
120
121 /*!
122 * Sets the raw data of the sound. When using this function,
123 * isIntern() will return 'true' until you use setUrl().
124 *
125 * \a data The raw data of the sound.
126 */
127 void setData(const QByteArray &data);
128
129 /*!
130 * Returns whether the sound is described by a URL (extern) or
131 * by the raw data (intern).
132 *
133 * When this method returns \c true you can use data() to
134 * get the raw data. Otherwise you can request the URL of this
135 * sound by url() and load the raw data from that location.
136 */
137 Q_REQUIRED_RESULT bool isIntern() const;
138
139 /*!
140 * Returns the location URL of this sound.
141 */
142 Q_REQUIRED_RESULT QString url() const;
143
144 /*!
145 * Returns the raw data of this sound.
146 */
147 Q_REQUIRED_RESULT QByteArray data() const;
148
149 /*!
150 * Returns string representation of the sound.
151 */
152 Q_REQUIRED_RESULT QString toString() const;
153
154private:
155 class Private;
156 QSharedDataPointer<Private> d;
157};
158
159/*!
160 * \relates KContacts::Sound
161 *
162 * Serializes the \a sound object into the \a stream.
163 */
164KCONTACTS_EXPORT QDataStream &operator<<(QDataStream &stream, const Sound &sound);
165
166/*!
167 * \relates KContacts::Sound
168 *
169 * Initializes the \a sound object from the \a stream.
170 */
171KCONTACTS_EXPORT QDataStream &operator>>(QDataStream &stream, Sound &sound);
172}
173Q_DECLARE_TYPEINFO(KContacts::Sound, Q_RELOCATABLE_TYPE);
174#endif
175

source code of kcontacts/src/sound.h