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

source code of kcontacts/src/sound.h