/*  This file is part of the KDE project.

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

This library is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 2.1 or 3 of the License.

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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this library.  If not, see <http://www.gnu.org/licenses/>.

*/

#ifndef PHONON_MMF_UTILS_H
#define PHONON_MMF_UTILS_H

#include <private/qcore_symbian_p.h>
#include <e32debug.h>   // for RDebug
#include <QtCore/QCoreApplication> // for Q_DECLARE_TR_FUNCTIONS
#include <QColor>

#include "defs.h"

QT_BEGIN_NAMESPACE

namespace Phonon
{
namespace MMF
{
/**
 * Panic codes for fatal errors
 */
enum PanicCode {
    InvalidStatePanic               = 1,
    InvalidMediaTypePanic           = 2,
    InvalidBackendInterfaceClass    = 3,
    AudioUtilityUrlNotSupported     = 4
};

class Utils
{
    Q_DECLARE_TR_FUNCTIONS(Utils)

public:
/**
 * Raise a fatal exception
 */
static void panic(PanicCode code);

/**
 * Determines whether the provided MIME type is an audio or video
 * type.  If it is neither, the function returns MediaTypeUnknown.
 */
static MediaType mimeTypeToMediaType(const TDesC& mimeType);

/**
 * Translates a Symbian error code into a user-readable string.
 */
static QString symbianErrorToString(int errorCode);

#ifndef QT_NO_DEBUG
/**
 * Retrieve color of specified pixel from the screen.
 */
static QColor getScreenPixel(const QPoint& pos);

/**
 * Samples a small number of pixels from the screen, and dumps their
 * colors to the debug log.
 */
static void dumpScreenPixelSample();
#endif
};

/**
 * Available trace categories;
 */
enum TTraceCategory {
    /**
     * Backend
     */
    EBackend             = 0x00000001,

    /**
     * Functions which map directly to the public Phonon audio API
     */
    EAudioApi            = 0x00000010,

    /**
     * Internal functions in the audio implementation
     */
    EAudioInternal       = 0x00000020,

    /**
     * Functions which map directly to the public Phonon video API
     */
    EVideoApi            = 0x00010000,

    /**
     * Internal functions in the video implementation
     */
    EVideoInternal       = 0x00020000
};

/**
 * Mask indicating which trace categories are enabled
 *
 * Note that, at the moment, this is a compiled static constant.  For
 * runtime control over enabled trace categories, this could be replaced
 * by a per-thread singleton object which owns the trace mask, and which
 * exposes an API allowing it to be modified.
 */
static const TUint KTraceMask = 0xffffffff;

/**
 * Data structure used by tracing macros
 */
class TTraceContext
{
public:
    TTraceContext(const TText* aFunction, const TUint aAddr,
                  const TUint aCategory = 0)
            :    iFunction(aFunction),
            iAddr(aAddr),
            iCategory(aCategory) { }

    /**
     * Check whether iCategory appears in the trace mask
     */
    TBool Enabled() const {
        return (iCategory == 0) or(iCategory & KTraceMask);
    }

    const TText*    iFunction;    // Name of function
    const TUint        iAddr;        // 'this' pointer
    const TUint        iCategory;
};

// Macros used internally by the trace system
#define _TRACE_PRINT RDebug::Print
#define _TRACE_TEXT(x) (TPtrC((const TText *)(x)))
#define _TRACE_MODULE Phonon::MMF

// Macros available for use by implementation code
#ifndef QT_NO_DEBUG
#define TRACE_CONTEXT(_fn, _cat) const ::Phonon::MMF::TTraceContext _tc((TText*)L ## #_fn, (TUint)this, _cat);
#define TRACE_ENTRY_0() { if (_tc.Enabled()) _TRACE_PRINT(_TRACE_TEXT(L ## "+ Phonon::MMF::%s [0x%08x]"), _tc.iFunction, _tc.iAddr); }
#define TRACE_ENTRY(string, args...) { if (_tc.Enabled()) _TRACE_PRINT(_TRACE_TEXT(L ## "+ Phonon::MMF::%s [0x%08x] " L ## string), _tc.iFunction, _tc.iAddr, args); }
#define TRACE_EXIT_0() { if (_tc.Enabled()) _TRACE_PRINT(_TRACE_TEXT(L ## "- Phonon::MMF::%s [0x%08x]"), _tc.iFunction, _tc.iAddr); }
#define TRACE_EXIT(string, args...) { if (_tc.Enabled()) _TRACE_PRINT(_TRACE_TEXT(L ## "- Phonon::MMF::%s [0x%08x] " L ## string), _tc.iFunction, _tc.iAddr, args); }
#define TRACE_RETURN(string, result) { if (_tc.Enabled()) _TRACE_PRINT(_TRACE_TEXT(L ## "r Phonon::MMF::%s [0x%08x] " L ## string), _tc.iFunction, _tc.iAddr, result); } return result;
#define TRACE_PANIC(code) { _TRACE_PRINT(_TRACE_TEXT(L ## "! Phonon::MMF::%s [0x%08x] panic %d"), _tc.iFunction, _tc.iAddr, code); } Utils::panic(code);
#define TRACE_0(string) { if (_tc.Enabled()) _TRACE_PRINT(_TRACE_TEXT(L ## "  Phonon::MMF::%s [0x%08x] " L ## string), _tc.iFunction, _tc.iAddr); }
#define TRACE(string, args...) { if (_tc.Enabled()) _TRACE_PRINT(_TRACE_TEXT(L ## "  Phonon::MMF::%s [0x%08x] " L ## string), _tc.iFunction, _tc.iAddr, args); }
#else
#define TRACE_CONTEXT(_fn, _cat)
#define TRACE_ENTRY_0()
#define TRACE_ENTRY(string, args...)
#define TRACE_EXIT_0()
#define TRACE_EXIT(string, args...)
#define TRACE_RETURN(string, result) return result;
#define TRACE_PANIC(code) Utils::panic(code);
#define TRACE_0(string)
#define TRACE(string, args...)
#endif
}
}

QT_END_NAMESPACE

#endif