1/*
2 This file is part of libkabc.
3 Copyright (c) 2002 Tobias Koenig <tokoe@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KABC_SOUND_H
22#define KABC_SOUND_H
23
24#include "kabc_export.h"
25#include <QtCore/QString>
26#include <QtCore/QSharedDataPointer>
27
28namespace KABC {
29
30/** @short Class that holds a Sound clip for a contact.
31 *
32 * The sound can be played doing something like this:
33 *
34 * \code
35 * KTempFile tmp;
36 * if ( sound.isIntern() ) {
37 * tmp.file()->write( sound.data() );
38 * tmp.close();
39 * KAudioPlayer::play( tmp.name() );
40 * } else if( !sound.url().isEmpty() ) {
41 * QString tmpFile;
42 * if ( !KIO::NetAccess::download( KUrl( themeURL.url() ), tmpFile, 0 ) ) {
43 * KMessageBox::error( 0,
44 * KIO::NetAccess::lastErrorString(),
45 * i18n( "Failed to download sound file" ),
46 * KMessageBox::Notify
47 * );
48 * return;
49 * }
50 * KAudioPlayer::play( tmpFile );
51 * }
52 * \endcode
53 *
54 * Unfortunately, KAudioPlayer::play is ASync, so to delete the temporary file
55 * the best you can really do is set a timer.
56 *
57 */
58class KABC_EXPORT Sound
59{
60 friend KABC_EXPORT QDataStream &operator<<( QDataStream &, const Sound & );
61 friend KABC_EXPORT QDataStream &operator>>( QDataStream &, Sound & );
62
63 public:
64
65 /**
66 * Creates an empty sound object.
67 */
68 Sound();
69
70 /**
71 * Creates a sound object for the given url.
72 *
73 * @param url A url that describes the position of the sound file.
74 */
75 Sound( const QString &url );
76
77 /**
78 * Creates a sound object for the given data.
79 *
80 * @param data The raw data of the sound.
81 */
82 Sound( const QByteArray &data );
83
84 /**
85 * Copy constructor.
86 */
87 Sound( const Sound &other );
88
89 /**
90 * Destroys the sound object.
91 */
92 ~Sound();
93
94 /**
95 * Assignment operator.
96 *
97 * @param other The sound object to assign to @c this
98 */
99 Sound &operator=( const Sound &other );
100
101 /**
102 * Equality operator.
103 *
104 * @param other The object to compare with
105 *
106 * @return @c true if the two objects are equal, otherwise @c false
107 */
108 bool operator==( const Sound &other ) const;
109
110 /**
111 * Not-Equal operator.
112 *
113 * @param other The object to compare with
114 *
115 * @return @c true if the two objects are not equal, otherwise @c false
116 */
117 bool operator!=( const Sound &other ) const;
118
119 /**
120 * Sets a URL for the location of the sound file. When using this
121 * function, isIntern() will return 'false' until you use
122 * setData().
123 *
124 * @param url The location URL of the sound file.
125 */
126 void setUrl( const QString &url );
127
128 /**
129 * Returns true, if the sound object is empty.
130 */
131 bool isEmpty() const;
132
133 /**
134 * Sets the raw data of the sound. When using this function,
135 * isIntern() will return 'true' until you use setUrl().
136 *
137 * @param data The raw data of the sound.
138 */
139 void setData( const QByteArray &data );
140
141 /**
142 * Returns whether the sound is described by a URL (extern) or
143 * by the raw data (intern).
144 * When this method returns 'true' you can use data() to
145 * get the raw data. Otherwise you can request the URL of this
146 * sound by url() and load the raw data from that location.
147 */
148 bool isIntern() const;
149
150 /**
151 * Returns the location URL of this sound.
152 */
153 QString url() const;
154
155 /**
156 * Returns the raw data of this sound.
157 */
158 QByteArray data() const;
159
160 /**
161 * Returns string representation of the sound.
162 */
163 QString toString() const;
164
165 private:
166 class Private;
167 QSharedDataPointer<Private> d;
168};
169
170/**
171 * Serializes the @p sound object into the @p stream.
172 */
173KABC_EXPORT QDataStream &operator<<( QDataStream &stream, const Sound &sound );
174
175/**
176 * Initializes the @p sound object from the @p stream.
177 */
178KABC_EXPORT QDataStream &operator>>( QDataStream &stream, Sound &sound );
179
180}
181
182#endif
183