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

#include <QObject>

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

#include "soundprovider.h"

#include "libkedusoundprovider_export.h"

/**
 * TaskData collects all non primitive data of a downlaod job started by the provider.
 * Stored in a map (see below) it allows to retrieve the associated data to any 
 * download job pending currently
 *
 * <li>QString item: the word to look for</li>
 * <li>KUrl remoteUrl: the remote URL the soundfile is located at </li>
 * <li>QString cacheName: the filename to store the sound file to 
 *     (normal file name plus path no file:// at the beginning)</li>
 * <li>QByteArray* soundData: the content of the sound file while downloading it</li>
 * <li>KIO:SimpleJob* job: the download job itself</li>
 * 
 * @see TaskDataMap
 */
typedef struct {
  QString item;
  KUrl remoteUrl;
  QString cacheName;
  QByteArray* soundData;
  KIO::SimpleJob* job;
} TaskData;

/**
 * TaskDataMap is a QMap storing TaskData pointers with the job pointer as key.
 */
typedef QMap<KJob*, TaskData*> TaskDataMap;

class LIBKEDUSOUNDPROVIDER_EXPORT WiktionaryProvider : public SoundProvider {
  Q_OBJECT
      
  public:
    WiktionaryProvider(QObject* parent);
    ~WiktionaryProvider();
    
    KUrl lookupSoundUrlForItem(QString lesson, QString item, QString lang, int loc);
    
    /**
     * The returned flag tells whether this implementation supports caching of 
     * remote data or not. This is merely a licensing issue, so for wiktionary we
     * have no problem and can easily support it.
     * @return true as this implementation supports and allows to cache the data.
     */
    bool supportsLocalCache() { return true; }
    
    /**
     * calls the KIO::Scheduler to cancel the job related to this remote soundfile URL.
     *
     * @param remoteUrl URL to identify the job downloading it via the taskdatamap
     * @see #m_taskData
     */
    void abortDownloadSoundUrl(KUrl remoteUrl);
    
  private Q_SLOTS:
    /**
     * slot used by the KIO::get job to signal progress infos. Used for debugging 
     * purposes only.
     */
    void infomsg(KJob* job, const QString& msg, const QString&);
    /**
     * slot used by the KIO::get job to provide chunks of data from the currently 
     * downloaded file.
     */
    void slotData(KIO::Job* job, const QByteArray& bytes);
    /**
     * slot used by the KIO::get job to signal that the download has finished either
     * successfully or with an error.
     * If the job was successful or if the remote Url refers to a valid sound file,
     * this method will emit the soundFileLoaded Signal
     *
     * @see #soundFileLoaded(QString, KUrl)
     */
    void slotResult(KJob *job);
    
  private:
    /**
     * helper method to ease job to check for dialects and possible alternative naming 
     * of the sound file location on wiktionary.
     *
     * @param item the word to look for
     * @param lang TWO digit language iso code (e.g. en for English, de for German)
     * @param loc location to look for, either LOCALCACHE or REMOTE. 
     *            See SoundProvider class for Details.
     *
     * @return local or remote URL of the soundfile or empty URL if none found.
     */
    KUrl lookupWiktionaryFor(QString item, QString lang, int loc);
    
    /**
     * QMap that stores the data associated with a downlaod job in a map 
     * with the job pointer as key. Allows to have all data to a job in a central
     * "repository".
     */
    TaskDataMap m_taskData;
    
    /**
     * class name of the provider used to specify in which 
     * kvtml apps / soundfiles sub directory to store the provider specific 
     * sound files. Not to be mixed up with the name / label the provider 
     * instances is registered at the factory !
     */
    static const char* PROVIDER_CLASS_NAME;
  
  Q_SIGNALS:
    /**
     * emitted when the provider has either finished downloading the file 
     * to local cache or in case local caching is not supported / activated has 
     * found a valid remote URL.
     *
     * @param item the word the sound file was downloaded for.
     * @param soundfileurl the URL to the soundfile to be played (by phonon e.g.)
     */
    void soundFileLoaded(QString /* thread ID key */item, KUrl soundfileurl);
};

#endif
