1 /*

     2  * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

     3  * All rights reserved.

     4  * This component and the accompanying materials are made available

     5  * under the terms of "Eclipse Public License v1.0"

     6  * which accompanies this distribution, and is available

     7  * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8  *

     9  * Initial Contributors:

    10  * Nokia Corporation - initial contribution.

    11  *

    12  * Contributors:

    13  *

    14  * Description:

    15  * This file defines the API for System Tone Service which is

    16  * implemented in the systemtoneservice.dll.  This API uses

    17  * the private implementation pattern to help improve the BC

    18  * of the API by decoupling the implementation from the

    19  * interface. 

    20  *

    21  */

    22 

    23 #ifndef __SYSTEMTONESERVICE_H__

    24 #define __SYSTEMTONESERVICE_H__

    25 

    26 // System includes

    27 #include <e32base.h>

    28 

    29 // Forward declarations

    30 NONSHARABLE_CLASS( CStsImplementation);

    31 

    32 // Class declaration

    33 /**

    34  *  System Tone Service API definition.

    35  *  This is the native C++ API for applications and middleware components

    36  *  to play standard system tones.

    37  *

    38  *  @code

    39  *   CSystemToneService* sts = CSystemToneService::Create();

    40  *   TInt calendarAlarmContext;

    41  *   ...

    42  *   if (sts)

    43  *   {

    44  *       ...

    45  *       sts->PlayTone(CSystemToneService::EWarningTone);

    46  *       ...

    47  *       sts->Playtone(CSystemToneService::ECalendarAlarm, &calendarAlarmContext);

    48  *       ...

    49  *   }

    50  *   ...

    51  *   sts->StopTone(calendarAlarmContext);

    52  *   ...

    53  *   CSystemToneService::Delete(sts);

    54  *  @endcode

    55  *

    56  */

    57 NONSHARABLE_CLASS(CSystemToneService) : public CBase

    58     {

    59 public:

    60     //** Constructor - returns NULL if construction fails */

    61     IMPORT_C static CSystemToneService* Create();

    62 

    63     //** Destructor */

    64     IMPORT_C static void Delete(CSystemToneService* aSystemToneService);

    65 

    66 public:

    67     // Data types

    68     /** The type of System Tones that are supported by this API. */

    69     enum TToneType

    70         {

    71         // Calendar Tones

    72         ECalendarAlarm = 0x0001,

    73         EClockAlarm = 0x0002,

    74         EToDoAlarm = 0x0003,

    75 

    76         // Capture Tones

    77         EBurstMode = 0x1001,

    78         ECapture = 0x1002,

    79         ECallRecording = 0x1003,

    80         ERecordingStart = 0x1004,

    81         ERecordingStop = 0x1005,

    82         ESelfTimer = 0x1006,

    83 

    84         // General Tones

    85         EConfirmationBeep = 0x2001,

    86         EDefaultBeep = 0x2002,

    87         EErrorBeep = 0x2003,

    88         EInformationBeep = 0x2004,

    89         EWarningBeep = 0x2005,

    90         EIntegratedHandsFreeActivated = 0x2006,

    91 

    92         // Key Tones

    93         ETouchScreen = 0x3001,

    94 

    95         // Location Tones

    96         ELocationRequest = 0x4001,

    97 

    98         // Messaging Tones

    99         EChatAlert = 0x5001,

   100         EEmailAlert = 0x5002,

   101         EMmsAlert = 0x5003,

   102         ESmsAlert = 0x5004,

   103         EDeliveryReport = 0x5005,

   104         EMessageSendFailure = 0x5006,

   105 

   106         // Power Tones

   107         EBatteryLow = 0x6001,

   108         EBatteryRecharged = 0x6002,

   109         EPowerOn = 0x6003,

   110         EPowerOff = 0x6004,

   111         EWakeUp = 0x6005,

   112         EWrongCharger = 0x6006,

   113 

   114         // Telephony Tones

   115         EIncomingCall = 0x7001,

   116         EIncomingCallLine2 = 0x7002,

   117         EIncomingDataCall = 0x7003,

   118         EAutomaticRedialComplete = 0x7004,

   119 

   120         // Voice Recognition Tones

   121         EVoiceStart = 0x8001,

   122         EVoiceError = 0x8002,

   123         EVoiceAbort = 0x8003

   124         };

   125 

   126     /**

   127      * Plays the specified tone.  If the tone type is not recognized a default tone will

   128      * be played.  This method is for fixed duration tones that are expected 

   129      * to play to completion and do not need to be stopped by the client.

   130      *

   131      * @param aTone An input parameter that indicates the type of tone to play.

   132      * @return description

   133      */

   134     IMPORT_C void PlayTone(TToneType aTone);

   135 

   136     /**

   137      * Plays the specified tone.  If the tone type is not recognized a default tone will

   138      * be played.  This method is used for tones that may not be fixed duration such as

   139      * infinitely looping tones, or for tones that can be manually stopped by the client.

   140      *

   141      * @param aTone An input parameter that indicates the type of tone to play.

   142      * @param aPlayToneContext An output parameter that provides back a unique context to

   143      *  the client for this tone play that can be used for stopping the playback.

   144      * @return description

   145      */

   146     IMPORT_C void PlayTone(TToneType aTone, unsigned int& aPlayToneContext);

   147 

   148     /**

   149      * Stops the specified tone playback.  If the playback has already completed or the

   150      * context is not recognized, this method does nothing.

   151      *

   152      * @param aPlayToneContext The context to the Tone Playing that is to be stopped.

   153      * @return description

   154      */

   155     IMPORT_C void StopTone(unsigned int aPlayToneContext);

   156 

   157 protected:

   158     // Protected constructors and destructors

   159     CSystemToneService(CStsImplementation& aImplementation);

   160     ~CSystemToneService();

   161 

   162 protected:

   163     // Protected data

   164     /**

   165      * A reference to the implementation class for this API.

   166      */

   167     CStsImplementation& iImplementation;

   168     };

   169 

   170 #endif  // __SYSTEMTONESERVICE_H__