//
// C++ Interface: soundprovider
//
// Description: 
//
//
// Author: Eitzenberger Thomas <kde@atpc310d>, (C) 2009
//
// Copyright: See COPYING file that comes with this distribution
//
//
#ifndef SOUNDPROVIDER_H
#define SOUNDPROVIDER_H

#include <QObject>

#include <KDebug>
#include <KUrl>

#include <kio/job.h>
#include <KJob>

#include "libkedusoundprovider_export.h"

class SoundProviderFactory;

/// This class provides an interface to support lookup / fetching  and playing sound files for a given item (e.g. Word) in a specified language.
/**
 * The following method needs to be implemented:
 * 
 * <pre>
 *   KUrl lookupSoundUrlForItem(QString lesson, QString item, QString lang, SoundLocation loc)
 * </pre>
 * 
 * The method is to look up if the specified item has a sound file available 
 * either cached locally or remotely. If no local cache data is avail you can call
 * the method with the REMOTE SoundLocation in which case it must 
 * download the remote sound url to a local cache folder and return the URL of the local
 * cache or the remote URL if the download failed or no local cache is supported 
 * but the remote URL is valid.
 * 
 * The SoundProviderFactory class provides an easy to use interface for supporting 
 * the sound file feature in kdeedu.
 *
 * @author Eitzenberger Thomas <eth@gmx.at>
*/
class LIBKEDUSOUNDPROVIDER_EXPORT SoundProvider : public QObject {
  Q_OBJECT
  public:
    /// Dumb virtual DTOR
    virtual ~SoundProvider();

    /// checks if a sound file is available for the given word, lesson, language tuppel. 
    /**
     * It depends on the implementing child class how the REMOTE location request 
     * is dealt with. It could just return the remote URL or support the cache feature
     * by overloading the appropriate method and download the remote file and return the
     * local URL.
     *
     * @param lesson ignored in current release - merely a left over
     * @param item the word to look up the sound file for.
     * @param lang language iso code (e.g. en for English, de for German),
     *             no dialects are supported, so dont call it with en-us but just en.
     * @param loc Location to look for the sound file. Either LOCALLY or REMOTELY.
     *
     * @return URL to the soundfile or empty URL if no sound file is found 
     *         on the given location
     * @see #supportsLocalCache()
     */
    virtual KUrl lookupSoundUrlForItem(QString lesson, QString item, QString lang, int loc) = 0;
    
    /// shall abort any pending download job regarding the given url.
    /**
     * The default implementation wont do anything but dump out a debug statement. 
     * Overwrite it in any specific provider implementation if you want to support this feature.
     *
     * @param remoteUrl the url specifying the download job to be aborted.
     */
    virtual void abortDownloadSoundUrl(KUrl remoteUrl);
    
    /// tells whether the implementing sound provider is able to cache data or not.
    /**
     * @return flag whether the implementation is able to cache data or not.
     */
    virtual bool supportsLocalCache() { return false; }
    
    /// allows to tell the sound provider implementation whether to store retrieved data locally for reuse or not.
    /** 
     * 
     * @param activate flag whether to cache and reuse retrieved data or not
    */
    void useLocalCache(bool activate);

    /// returns a flag whether this soundprovider has local cache activated or not.
    /**
     * @return flag whether local cache is active or not.
     */
    bool localCacheActive() { return m_localCache && supportsLocalCache(); }

    /// returns the name of the SoundProvider as specified when registered at factory.
    /**
     * @return name of the provider as registered at the factory.
     */
    QString name() { return m_providerName; }

    /// returns the priority of the SoundProvider as specified when registered at factory.
    /**
     * Valid range is from 0 to 100 where 100 is highest priority.
     * @return priority of this provider at the factory.
     */
    int priority() { return m_priority; }


    /// ID to tell the lookup method to search in local cache for a sound file.
    static const int LOCALCACHE = 1;
    
    /// ID to tell the lookup method to search remotely (via e.g. HTTP request) for a sound file.
    static const int REMOTE = 2;

  protected:
    /// flag whether the soundprovider shall use a local cache or not.
    bool m_localCache;

    /// Dummy empty CTOR.
    SoundProvider(QObject* parent);
 
    /// checks the default KDE folder structures and returns the filename to be used for local storage of downloaded sound files.
    /**
     *
     * Currently known implementations and thus reserved names are:
     * <pre>
     *   o "wiktionary"
     * </pre>
     *
     * @param providerclass unique name for the implemented provider.
     * @param item the word to look for
     * @param lang the TWO digit iso language code
     *
     * @return the local cache file name
     */
    QString getLocalCacheName(QString providerclass, QString item, QString lang);
      
  private:
    /// name of the soundprovider under which it is registered at the factory.
    QString m_providerName;
    
    /// priority of the soundprovider (0-100). 
    /**
     * Specifies the order in which the soundproviders will be contacted when searching for a sound file by the factory.
     */
    int m_priority;

    /** 
     * for accessing the priority and name members 
     */
    friend class SoundProviderFactory;
};

#endif
