/*
* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
*
* This program 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, version 2.1 of the License.
* 
* This program 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 program.  If not, 
* see "http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html/".
*
* Description:
*       QT wrapper API for  for System Tone Service 
*
*/

#ifndef XQSYSTEMTONESERVICE_H
#define XQSYSTEMTONESERVICE_H

#include <QObject>

#include <systemtoneservice.h>

#ifdef __STS_QT_LIB_BUILD__ 
#  define STS_EXPORT Q_DECL_EXPORT
#else
#  define STS_EXPORT Q_DECL_IMPORT
#endif

class XQSystemToneServicePrivate;

/**
 * The System Tone Service (STS) is a component of the Multimedia Services (mmserv) 
 * collection of the Multimedia Middleware (mmmw) package. STS provides multimedia APIs 
 * specific to playing system tones (calendar, message alerts, warnings, etc).
 * 
 * Here you can find Qt wrapper for this component.
 * 
 * Main concepts behind this API:
 *   * tone - short sound used in the manner "fire and forget" therefore there are no signals when tone ends.
 *   * alarm - these are kind of looped/longer sounds that may be interrupted by calling app; also there are notifications (signals) when alarm ends playing.
 *    
 */
class XQSystemToneService : public QObject
{
  Q_OBJECT

public:

/**
 * Supported tone types.
*/
  Q_DECL_IMPORT enum ToneType {
	   // Capture Tones
	   BurstModeTone = CSystemToneService::EBurstMode,
	   CaptureTone = CSystemToneService::ECapture,
	   CallRecordingTone = CSystemToneService::ECallRecording,
	   RecordingStartTone = CSystemToneService::ERecordingStart,
	   RecordingStopTone = CSystemToneService::ERecordingStop,
	   SelfTimerTone = CSystemToneService::ESelfTimer,
	   
	   // General Tones
	   ConfirmationBeepTone = CSystemToneService::EConfirmationBeep,
	   DefaultBeepTone = CSystemToneService::EDefaultBeep,
	   ErrorBeepTone = CSystemToneService::EErrorBeep,
	   InformationBeepTone = CSystemToneService::EInformationBeep,
	   WarningBeepTone = CSystemToneService::EWarningBeep,
	   IntegratedHandsFreeActivatedTone = CSystemToneService::EIntegratedHandsFreeActivated,
	   
	   // Key Tones
	   TouchScreenTone = CSystemToneService::ETouchScreen,
	   
	   // Location Tones
	   LocationRequestTone = CSystemToneService::ELocationRequest,
	   
	   // Messaging Tones
	   ChatAlertTone = CSystemToneService::EChatAlert,
	   EmailAlertTone = CSystemToneService::EEmailAlert,
	   MmsAlertTone = CSystemToneService::EMmsAlert,
	   SmsAlertTone = CSystemToneService::ESmsAlert,
	   DeliveryReportTone = CSystemToneService::EDeliveryReport,
	   MessageSendFailureTone = CSystemToneService::EMessageSendFailure,
	   
	   // Power Tones
	   BatteryLowTone = CSystemToneService::EBatteryLow,
	   BatteryRechargedTone = CSystemToneService::EBatteryRecharged,
	   PowerOnTone = CSystemToneService::EPowerOn,
	   PowerOffTone = CSystemToneService::EPowerOff,
	   WakeUpTone = CSystemToneService::EWakeUp,
	   WrongChargerTone = CSystemToneService::EWrongCharger,
	   
	   // Telephony Tones
	   AutomaticRedialCompleteTone = CSystemToneService::EAutomaticRedialComplete,
	   
	   // Voice Recognition Tones
	   VoiceStartTone = CSystemToneService::EVoiceStart,
	   VoiceErrorTone = CSystemToneService::EVoiceError,
	   VoiceAbortTone = CSystemToneService::EVoiceAbort
  };
  
Q_DECL_IMPORT enum AlarmType {
       // Calendar Tones
       CalendarAlarmTone = CSystemToneService::ECalendarAlarm,
       ClockAlarmTone = CSystemToneService::EClockAlarm,
       ToDoAlarmTone = CSystemToneService::EToDoAlarm,

       // Telephony Alarms
       IncomingCallTone = CSystemToneService::EIncomingCall,
       IncomingCallLine2Tone = CSystemToneService::EIncomingCallLine2,
       IncomingDataCallTone = CSystemToneService::EIncomingDataCall,
  };

  
public:
/**
* XQSystemToneService object constructor. 
*/
  STS_EXPORT XQSystemToneService(QObject *parent = 0);

/**
* Simple destructor.
*/
  STS_EXPORT ~XQSystemToneService();

/**
* Play selected tone.
*
* @param  toneType  selected tone type.
* @see  XQSystemToneService::error()
*/
  STS_EXPORT void playTone(ToneType toneType);

/**
* Play selected alarm. 
*
* @param  alarmType  selected tone type.
* @param  contextId  unique playback id for current playback event. May be used for matching playback signals and/or to later stop playing.
* @see  XQSystemToneService::stopAlarm(unsigned int contextId)
* @see  XQSystemToneService::error()
*/
  STS_EXPORT void playAlarm(AlarmType alarmType, unsigned int& contextId);
  
  
/**
* Cancel tone being played currently.
*
* @param contextId id, must be same as given by playTone method.
* @see  XQSystemToneService::playAlarm(ToneType toneType, unsigned int& contextId)
*/
  STS_EXPORT void stopAlarm(unsigned int contextId);

/**
* Play selected tone. 
*
* @param  toneType  selected tone type.
* @param  contextId  unique playback id for current playback event. May be used for matching playback signals and/or to later stop playing.
* @see  XQSystemToneService::stopAlarm(unsigned int contextId)
* @see  XQSystemToneService::error()
*/
  STS_EXPORT void playAlarm(ToneType toneType, unsigned int& contextId);
  
signals:

/**
* Playback of given tone has been started.
* 
*/
  STS_EXPORT void toneStarted();

/**
* Playback of given alarm has been started.
*
* @param contextId id, the same as given by playTone method.
* 
*/
  STS_EXPORT void alarmStarted(unsigned int contextId);
  
/**
* Playback of given alarm has been finished.
*
* @param contextId id, the same as given by playTone method.
* 
*/
  STS_EXPORT void alarmFinished(unsigned int contextId);

private:

  XQSystemToneServicePrivate *d_p;

  friend class XQSystemToneServicePrivate;
  
};

#endif /*SYSTEMTONESERVICE_QT_H*/