/*

    This file is part of the KDE project

    Copyright (C) 2005-2007 Matthias Kretz <kretz@kde.org>

    Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

    Contact: Nokia Corporation (qt-info@nokia.com)

    This library is free software; you can redistribute it and/or

    modify it under the terms of the GNU Library General Public

    License version 2 as published by the Free Software Foundation.

    This library is distributed in the hope that it will be useful,

    but WITHOUT ANY WARRANTY; without even the implied warranty of

    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

    Library General Public License for more details.

    You should have received a copy of the GNU Library General Public License

    along with this library; see the file COPYING.LIB.  If not, write to

    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,

    Boston, MA 02110-1301, USA.

*/

/*!

    \enum Phonon::DiscType

    Enum to identify the media discs supported by MediaObject.

    \value NoDisc

    No disc was selected. This is only useful as a return value from

    MediaSource::diskType().

    \value Cd Identifies Audio CDs.

    \value Dvd Identifies DVDs (not arbitrary data DVDs, only movie DVDs).

    \value Vcd Identifies Video CDs.

    \sa MediaSource, MediaObject

*/

/*!

    \enum Phonon::MetaData

    Provided as keys for Phonon::MediaObject::metaData(). The enum

    values matches strings defined in the Ogg Vorbis specification

    \value ArtistMetaData

    \value AlbumMetaData

    \value TitleMetaData

    \value DateMetaData

    \value GenreMetaData

    \value TracknumberMetaData

    \value DescriptionMetaData

    \value MusicBrainzDiscIdMetaData

*/

/*!

    \enum Phonon::State

    \since 4.4

    The state enum describes the different states a media object can

    take. Several functions of \l{Phonon::}{MediaObject} are

    asynchronous, so even if a you have requested a state change

    through a function call, e.g., through

    \l{Phonon::MediaObject::}{play()}, you cannot be sure that the

    change has taken place before you receive the

    \l{Phonon::MediaObject::}{stateChanged()} signal.

    A media object can at any time change into any state, regardless

    of the state it previously had. \omit In the

    \l{Phonon::}{MediaObject} class description explains the typical

    state changes in the life of a media object. \endomit

    \value LoadingState

    After construction it might take a while before the media object

    is ready to \l{Phonon::MediaObject::}{play()}. This state is

    commonly used by backends to initialize the \l{Phonon

    Overview}{media graph} and loading the source. When

    the object leaves the loading state, it will enter the

    StoppedState unless an error occurred or another state is

    requested through a function call, e.g.,

    \l{Phonon::}{MediaObject::play()}.

    \value StoppedState

    In the stopped state, the media object is ready to play its

    current media source. The current

    \l{MediaObject::seek()}{position} in the media stream is then 0.

    \value PlayingState

    The media object is playing back its media source.

    \value BufferingState

    The Player is waiting for data to be able to start or continue

    playing. This state is commonly used to wait for media data over a

    network connection.

    \value PausedState

    The media player has currently paused its playback, i.e., it

    stops playing but keeps the current playback position in the

    stream.

    \value ErrorState

    When a media object enters the error state a problem with the

    playback has occurred. The possible errors are grouped into

    two categories by Phonon::ErrorType, and the type can be

    queried through \l{Phonon::MediaObject::}{errorType()}. A

    \l{Phonon::}{FatalError} implies that the playback

    cannot continue, but one can still try with a new media

    source. With a \l{Phonon::}{NormalError} it might

    be possible to continue playback, and a media object may

    therefore change state from the ErrorState.

    \sa MediaObject

*/

/*!

    \enum Phonon::Category

    Sets the category your program should be listed in in the mixer.

    \value NoCategory

    Will make use of the default device.

    \value NotificationCategory

    If the sounds produced are notifications (ping, beep and such) you

    should use this category.

    \value MusicCategory

    If your application is a music player (like a jukebox or media player

    playing an audio file).

    \value VideoCategory

    If the sound is the audio channel of a video.

    \value CommunicationCategory

    If your applications produces sounds from communication with somebody

    else (VoIP, voice chat).

    \value GameCategory

    Sound produced by a computer game should go into this category.

    \value AccessibilityCategory

    Sounds produced for accessibility (e.g., Text-To-Speech)

    \omitvalue LastCategory

    Holds the largest value of categories.

    \omitvalue AccessibilityCategory

    A Jukebox will set this to Music, a VoIP program to Communication, a

    DVD player to video, and so on.

    \note These categories can also become useful for an application that

    controls the volumes automatically, like turning down the music when a call

    comes in, or turning down the notifications when the media player knows

    it's playing classical music.

*/

/*!

    \enum Phonon::ErrorType

    This enum describes the severity when an error has occurred during

    playback.

    After a media object has entered the \l{Phonon::}{ErrorState}, one

    can query the type of error from

    \l{Phonon::}{MediaObject::errorType()}. Note that you should query

    the error when receiving the

    \l{Phonon::}{MediaObject::stateChanged()} signal, because the

    error type will be lost if the media object leaves the error

    state.    

    \value NoError No error. MediaObject::errorType() returns this if

    MediaObject::state() != Phonon::ErrorState.

    \value NormalError An error has occurred with the playback of the current

    source. It might be possible to continue playback, for instance, if only the

    audio stream in a video cannot be played back. The media object will then

    leave the error state again.

    \value FatalError. Something important does not work. Your program cannot continue

    the playback of the current source, but it might be possible to try another.

    \sa MediaObject::errorType()

*/

/*!

    \fn QString Phonon::categoryToString(Category c)

    Returns a (translated) string to show to the user identifying the given

    Category (\a c).

*/

/*!

    \enum Phonon::ObjectDescriptionType

    \relates Phonon::ObjectDescription

    This enum defines the type of information that is contained in a

    \l{Phonon::}{ObjectDescription} object.

    \value AudioOutputDeviceType An audio output device (\l{Phonon::}{AudioOutputDevice}).

    This can be soundcards (with different drivers),

    sound servers, or other virtual outputs like playback on a different

    computer on the network.

    \value EffectType An audio effect (\l{Phonon::}{EffectDescription}).

    \omitvalue SubtitleType

    \omitvalue AudioCaptureDeviceType

    \omitvalue AudioChannelType

*/

/*!

    \typedef Phonon::AudioOutputDevice

    \relates Phonon::ObjectDescription

    This typedef of \l{Phonon::}{ObjectDescription} describes an audio output

    device, such as soundcards (with different drivers), sound servers, or other

    virtual outputs like playback on a different computer on the network.

    \omit

    For Hardware devices the backend should use libkaudiodevicelist

    (AudioDevice and AudioDeviceEnumerator) which will list removable

    devices even when they are unplugged and provide a unique identifier

    that can make backends use the same identifiers.

    \endomit

    A list of available devices is given by the backend with

    Backendcapabilities::availableAudioOutputDevices()

    \snippet doc/src/snippets/phononobjectdescription.cpp 1

*/

/*!

    \fn Phonon::phononVersion()

    \inmodule Phonon

    \since 4.5

    Returns the Phonon version.

*/

/*!

    \class Phonon::ObjectDescription

    \inmodule Phonon

    \inheaderfile Phonon/ObjectDescription

    \since 4.4

    \brief The ObjectDescription class provides information about Phonon objects.

    Phonon currently uses this class to describe audio effects and

    audio output devices - using the typedefs AudioOutputDevice and

    EffectDescription. The type of an ObjectDescription is also

    described through the \l{Phonon::}{ObjectDescriptionType} enum.

    Objects of the same \l{Phonon::ObjectDescriptionType}{type} are

    uniquely identified by an index().

    The class gives a description() and a name() of the object, both

    of which are strings appropriate for end users of a Phonon

    application. You can also check whether the device or effect

    described is \l{isValid()}{valid}. This does not guarantee that

    the device or effect functions as expected, but that the

    ObjectDescription describes an existing device or effect.

    Audio output devices and effect descriptions are used to select

    the audio output device to be used for playback and to create

    effects; we show examples of this in the snippet below. The

    available descriptions can be fetched with

    \l{Phonon::BackendCapabilities::}{availableAudioOutputDevices()}

    and \l{Phonon::BackendCapabilities::}{availableAudioEffects()}

    static functions in the Phonon::BackendCapabilities namespace

    \snippet doc/src/snippets/phononobjectdescription.cpp 0

    Other types of ObjectDescriptions might be possible in the future,

    e.g., descriptions of audio capture devices, such as microphones.

    \omit Not implemented yet.

    Need a new paragraph on that some descriptions 'belong

    together', such as chained audio effects.

    Some parts give the end user choices, e.g. what source to capture

    audio from. These choices are described by the name and

    description methods of this class and identified with the id

    method. Subclasses then define additional information like which

    audio and video choices belong together.  \endomit

    \sa Phonon::AudioOutputDevice, Phonon::EffectDescription, {Capabilities Example}, {Phonon Module}

*/

/*!

    \fn Phonon::ObjectDescription::ObjectDescription()

    \brief constructs a new object description.

    \internal

*/

/*!

    \fn Phonon::ObjectDescription::ObjectDescription (int index, const QHash<QByteArray, QVariant> & properties)

    \internal

*/

/*!

    \fn Phonon::ObjectDescription::ObjectDescription(const QExplicitlySharedDataPointer<ObjectDescriptionData> &dd)

    \internal

*/

/*!

    \fn static inline ObjectDescription<T> Phonon::ObjectDescription::fromIndex(int index)

    \internal

    \omit Currently indices are not unique for all ObjectDescription types, making

    the behavior of this function undefined. \endomit

    Returns a new description object that describes the

    device/effect/codec/...  with the given \a index.

*/

/*!

    \fn inline bool Phonon::ObjectDescription::operator==(const ObjectDescription &otherDescription) const

    Returns \c true if this ObjectDescription describes the same

    object as \a otherDescription; otherwise, returns \c false.

*/

/*!

    \fn inline bool Phonon::ObjectDescription::operator!=(const ObjectDescription &otherDescription) const

    Returns \c false if this ObjectDescription describes the same

    as \a otherDescription; otherwise, returns \c true.

*/

/*!

    \fn inline QString Phonon::ObjectDescription::name() const

    Returns a string appropriate for a user to select between

    object descriptions, e.g., from a QComboBox.

    \sa description()

*/

/*!

    \fn inline QString Phonon::ObjectDescription::description() const

    Returns a more extensive description than the name() function.

    For example, in the case of \l{Phonon::}{AudioOutputDevice}s, this

    text should make clear which sound source is described; this is

    sometimes hard to describe or understand from just the name.

    The text is appropriate to present to an end user in for example

    tool tips of items, with the name()'s as text, in a QComboBox.

*/

/*!

    \fn inline QVariant Phonon::ObjectDescription::property(const char *name) const

    Returns the property named \a name. A property can be used for

    extended information, such as the manufacturer of a sound card. The

    information will usually be given as text.

    If the property is not set an invalid QVariant is returned.

    Qt's backends do not use properties at the time of this writing.

    \sa propertyNames()

*/

/*!

    \fn inline QList<QByteArray> Phonon::ObjectDescription::propertyNames() const

    Properties can be used for extended information about a

    ObjectDescription, e.g., a manufacturer of a sound card. The

    information will usually be given text.

    This function returns all names that return valid data when

    property() is called.

    Currently, Qt backends do not use properties for their object

    descriptions.

    \sa property()

*/

/*!

    \fn inline bool Phonon::ObjectDescription::isValid() const

    Returns true if the device or effect described exists.

    An ObjectDescription that is invalid, will also have an

    index() of -1.

    \sa index()

*/

/*!

    \fn inline int Phonon::ObjectDescription::index() const

    Returns a unique identifier for this ObjectDescription. Used

    internally to distinguish between the descriptions.

    Notice that the identifiers are only unique to the type of

    description, e.g., \l{Phonon::}{AudioOutputDevice} or

    \l{Phonon::}{EffectDescription}.

*/

/*!

    \class Phonon::ObjectDescriptionPrivate

    \inmodule Phonon

    \since 4.4

    \internal

*/

/*!

    \class Phonon::StreamInterface

    \inmodule Phonon

    \since 4.4

    \brief Backend interface to handle media streams (AbstractMediaStream).

    \internal

*/

/*!

    \fn virtual Phonon::StreamInterface::~StreamInterface()

*/

/*!

    \fn virtual void Phonon::StreamInterface::writeData(const QByteArray &data) = 0

    \internal

*/

/*!

    \fn virtual void Phonon::StreamInterface::endOfData() = 0

    \internal

*/

/*!

    \fn virtual void Phonon::StreamInterface::setStreamSize(qint64 newSize) = 0

    \internal

*/

/*!

    \fn virtual void Phonon::StreamInterface::setStreamSeekable(bool s) = 0

    \internal

*/

/*!

    \fn void Phonon::StreamInterface::connectToSource(const MediaSource &mediaSource)

    \internal

*/

/*!

    \fn void Phonon::StreamInterface::needData()

    \internal

*/

/*!

    \fn void Phonon::StreamInterface::enoughData()

    \internal

*/

/*!

    \fn void Phonon::StreamInterface::seekStream(qint64)

    \internal

*/

/*!

    \fn void Phonon::StreamInterface::reset()

    \internal

*/

/*!

    \fn Phonon::StreamInterface::StreamInterface()

    \internal

    \omit

    For subclasses.

    \endomit

*/

/*!

    \class StreamInterfacePrivate

    \inmodule Phonon

    \internal

*/

/*!

    \class Phonon::AbstractVideoOutput

    \inmodule Phonon

    \internal

    \since 4.4

    \brief The AbstractVideoOutput class is the common base class for all video output classes.

    \sa VideoWidget

*/

/*!

    \namespace Phonon::Experimental

    \internal

*/

/*!

    \fn Phonon::AbstractVideoOutput::AbstractVideoOutput(AbstractVideoOutputPrivate &d)

    \internal

    Constructor that is called from derived classes.

    \param parent Standard QObject parent.

*/

/*!

    \class Phonon::AbstractVideoOutputPrivate

    \inmodule Phonon

    \internal

    \since 4.4

*/

/*!

    \class Phonon::VolumeFaderEffect

    \inmodule Phonon

    \internal

    \since 4.4

    This effect differs from gradually changing the output volume in that

    a dedicated effect can change the volume in the smallest possible

    steps while every other volume control will make more or less

    noticeable steps.

    \sa AudioOutput::volume()

*/

/*!

    \property Phonon::VolumeFaderEffect::volume

    This is the current volume of the output as voltage factor.

    Setting this property changes the volume immediately.

    1.0 means 100%, 0.5 means 50% voltage/25% power, 0.0 means 0%

    \sa volumeDecibel

*/

/*!

    \property Phonon::VolumeFaderEffect::volumeDecibel