/*
 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).
 * All rights reserved.
 * This component and the accompanying materials are made available
 * under the terms of "Eclipse Public License v1.0"
 * which accompanies this distribution, and is available
 * at the URL "http://www.eclipse.org/legal/epl-v10.html".
 *
 * Initial Contributors:
 * Nokia Corporation - initial contribution.
 *
 * Contributors:
 *
 * Description:
 * This file defines the API for System Tone Service which is
 * implemented in the systemtoneservice.dll.  This API uses
 * the private implementation pattern to help improve the BC
 * of the API by decoupling the implementation from the
 * interface. 
 *
 */

#ifndef __SYSTEMTONESERVICE_H__
#define __SYSTEMTONESERVICE_H__

// System includes
#include <e32base.h>

// Forward declarations
NONSHARABLE_CLASS( CStsImplementation);

// Class declaration
/**
 *  System Tone Service API definition.
 *  This is the native C++ API for applications and middleware components
 *  to play standard system tones.
 *
 *  @code
 *   CSystemToneService* sts = CSystemToneService::Create();
 *   TInt calendarAlarmContext;
 *   ...
 *   if (sts)
 *   {
 *       ...
 *       sts->PlayTone(CSystemToneService::EWarningTone);
 *       ...
 *       sts->Playtone(CSystemToneService::ECalendarAlarm, &calendarAlarmContext);
 *       ...
 *   }
 *   ...
 *   sts->StopTone(calendarAlarmContext);
 *   ...
 *   CSystemToneService::Delete(sts);
 *  @endcode
 *
 */
NONSHARABLE_CLASS(CSystemToneService) : public CBase
    {
public:
    //** Constructor - returns NULL if construction fails */
    IMPORT_C static CSystemToneService* Create();

    //** Destructor */
    IMPORT_C static void Delete(CSystemToneService* aSystemToneService);

public:
    // Data types
    /** The type of System Tones that are supported by this API. */
    enum TToneType
        {
        // Calendar Tones
        ECalendarAlarm = 0x0001,
        EClockAlarm = 0x0002,
        EToDoAlarm = 0x0003,

        // Capture Tones
        EBurstMode = 0x1001,
        ECapture = 0x1002,
        ECallRecording = 0x1003,
        ERecordingStart = 0x1004,
        ERecordingStop = 0x1005,
        ESelfTimer = 0x1006,

        // General Tones
        EConfirmationBeep = 0x2001,
        EDefaultBeep = 0x2002,
        EErrorBeep = 0x2003,
        EInformationBeep = 0x2004,
        EWarningBeep = 0x2005,
        EIntegratedHandsFreeActivated = 0x2006,

        // Key Tones
        ETouchScreen = 0x3001,

        // Location Tones
        ELocationRequest = 0x4001,

        // Messaging Tones
        EChatAlert = 0x5001,
        EEmailAlert = 0x5002,
        EMmsAlert = 0x5003,
        ESmsAlert = 0x5004,
        EDeliveryReport = 0x5005,
        EMessageSendFailure = 0x5006,

        // Power Tones
        EBatteryLow = 0x6001,
        EBatteryRecharged = 0x6002,
        EPowerOn = 0x6003,
        EPowerOff = 0x6004,
        EWakeUp = 0x6005,
        EWrongCharger = 0x6006,

        // Telephony Tones
        EIncomingCall = 0x7001,
        EIncomingCallLine2 = 0x7002,
        EIncomingDataCall = 0x7003,
        EAutomaticRedialComplete = 0x7004,

        // Voice Recognition Tones
        EVoiceStart = 0x8001,
        EVoiceError = 0x8002,
        EVoiceAbort = 0x8003
        };

    /**
     * Plays the specified tone.  If the tone type is not recognized a default tone will
     * be played.  This method is for fixed duration tones that are expected 
     * to play to completion and do not need to be stopped by the client.
     *
     * @param aTone An input parameter that indicates the type of tone to play.
     * @return description
     */
    IMPORT_C void PlayTone(TToneType aTone);

    /**
     * Plays the specified tone.  If the tone type is not recognized a default tone will
     * be played.  This method is used for tones that may not be fixed duration such as
     * infinitely looping tones, or for tones that can be manually stopped by the client.
     *
     * @param aTone An input parameter that indicates the type of tone to play.
     * @param aPlayToneContext An output parameter that provides back a unique context to
     *  the client for this tone play that can be used for stopping the playback.
     * @return description
     */
    IMPORT_C void PlayTone(TToneType aTone, unsigned int& aPlayToneContext);

    /**
     * Stops the specified tone playback.  If the playback has already completed or the
     * context is not recognized, this method does nothing.
     *
     * @param aPlayToneContext The context to the Tone Playing that is to be stopped.
     * @return description
     */
    IMPORT_C void StopTone(unsigned int aPlayToneContext);

protected:
    // Protected constructors and destructors
    CSystemToneService(CStsImplementation& aImplementation);
    ~CSystemToneService();

protected:
    // Protected data
    /**
     * A reference to the implementation class for this API.
     */
    CStsImplementation& iImplementation;
    };

#endif  // __SYSTEMTONESERVICE_H__