1 /*

     2 * Copyright (c) 2007 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:  Communication from Client API to Tactile Area Registry.

    15 * Part of:      Tactile Feedback.

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef C_TOUCHFEEDBACKCLIENT_H

    22 #define C_TOUCHFEEDBACKCLIENT_H

    23 

    24 #include <e32std.h>

    25 #include <w32std.h>

    26 #include <e32base.h>

    27 #include <coemain.h>

    28 #include <tactilefeedback.h>

    29 

    30 #include "touchlogicalfeedback.h"

    31 

    32 class CTouchFeedbackImpl;

    33 

    34 /**

    35  *  The class for sharing area registry with the window server.

    36  *

    37  *  @lib touchfeedback.lib

    38  *  @since S60 v5.0

    39  */

    40 NONSHARABLE_CLASS( CTouchFeedbackClient ): 

    41         public CBase

    42     {

    43 public:

    44     /**

    45      * Instantiation method.

    46      *

    47      * @since S60 5.0

    48      * @return New CTouchFeedbackClient instance.

    49      */

    50     static CTouchFeedbackClient* NewL( CTouchFeedbackImpl& aFeedback );

    51 

    52     /**

    53      * Destructor.

    54      * @since S60 5.0

    55      */

    56     virtual ~CTouchFeedbackClient();

    57         

    58     /**

    59      * Should be called whenever registry has changed.

    60      *

    61      * Causes starting of a CIdle object, so that registry updates are

    62      * flushed to server side as soon as possible.

    63      * @since S60 5.0     

    64      */

    65     void RegistryChanged( );

    66 

    67     /**

    68      * Use to produce direct feedback immediately.

    69      *

    70      * @since S60 5.0     

    71      * @param aType    - The logical feedback type.

    72      * @param aVibraOn - If ETrue then vibra feedback shall be played

    73      *                   (if enabled in device).

    74      * @param aAudioOn - If ETrue then audio feedback shall be played

    75      *                   (if enabled in device).

    76      */

    77     void ImmediateFeedback( TTouchLogicalFeedback aType, 

    78                             TBool aVibraOn, 

    79                             TBool aAudioOn );

    80 

    81     /**

    82      * Use to flush registry updates immediately.

    83      * @since S60 5.0     

    84      */

    85     void FlushUpdates();

    86     

    87     /**

    88      * Starts continuous feedback or just restarts the timeout timer if 

    89      * feedback is already started. This function can also be used to

    90      * modify the intensity of ongoing continuous feedback if timeout 

    91      * and repeated start calls are used. 

    92      *

    93      * @since S60 5.2     

    94      * @param aClientHandle - Handle of a client. Handle is stored to 

    95      *                        prevent other clients to stop or modify 

    96      *                        playing feedback.

    97      * @param aType         - Type of continuous feedback.

    98      *                   

    99      * @param aIntensity    - Intensity of continuous feedback. Value

   100      *                        range is 0-100%.

   101      * @param aTimeout      - Timeout value, which is used to automatically 

   102      *                        stop continuous feedback if there's no new 

   103      *                        start call within the timeout time. 

   104      */    

   105     void StartFeedback( TUint32 aClientHandle,

   106                         TTouchContinuousFeedback aType,

   107                         TInt aIntensity,

   108                         TTimeIntervalMicroSeconds32 aTimeout );

   109                         

   110     /**

   111      * Modifies the intensity of continuous feedback.

   112      *

   113      * @since S60 5.2     

   114      * @param aClientHandle - Handle of a client to check if caller started

   115      *                        the playing continuous feedback. 

   116      * @param aIntensity    - New intensity of continuous feedback. Value

   117      *                        range is 0-100%.

   118      */                            

   119     void ModifyFeedback( TUint32 aClientHandle,

   120                          TInt aIntensity );

   121     

   122     /**

   123      * Stops the continuous feedback.

   124      *

   125      * @since S60 5.2     

   126      * @param aClientHandle - Handle of a client to check if caller started

   127      *                        the playing continuous feedback. 

   128      */                                

   129     void StopFeedback( TUint32 aClientHandle );  

   130 

   131     /**

   132      * Enables or disables audio or/and vibra feedback in whole device.

   133      * @param aFeedbackType  - Feedback types to be enabled/disabled 

   134      *                         defined as a bitmask combination of 

   135      *                         enumeration items from TTouchFeedbackType.

   136      *

   137      * @since S60 5.2     

   138      * @return KErrNone, or one of standard Symbian OS error codes if

   139      *         enabling/disabling fails.

   140      *         KErrPermissionDenied - ECapabilityWriteDeviceData required

   141      *                                for using this function.

   142      */    

   143     TInt SetFeedbackEnabledForDevice( TTouchFeedbackType aFeedbackType );  

   144 

   145     /**

   146      * Used to check enabled feedback types for the device.

   147      *

   148      * @since S60 5.2

   149      * @return TTouchFeedbackType containing enabled feedback types 

   150      *         as a bitmask.

   151      */    

   152     TTouchFeedbackType FeedbackEnabledForDevice();

   153 

   154 private:

   155 

   156     /**

   157      * Start timeout timer for continuous feedback.

   158      */

   159     void StartFeedbackTimer( TTimeIntervalMicroSeconds32 aTimeout );

   160     

   161     /**

   162      * Stops continuous feedback and clears timeout timer and client handle.

   163      * Called by timeout callback function.

   164      */    

   165     void StopFeedbackByTimeout();

   166     

   167     /**

   168      * Timeout callback function.

   169      */

   170      static TInt StopFeedbackCallback( TAny* aThis );

   171     

   172 private:

   173 

   174     /**

   175      * Default constructor.

   176      */

   177     CTouchFeedbackClient( CTouchFeedbackImpl& aFeedback );

   178 

   179     /**

   180      * 2nd phase constructor.

   181      */    

   182     void ConstructL();

   183 

   184     /**

   185      * Callback for CIdle. When this function is called, it is time to update

   186      * local registry content to shared memory chunk.

   187      *

   188      * Depending of whether feedback is actually enabled or disabled for

   189      * this application, either UpdateRegistryToChunkL or ClearWholeChunkL

   190      * -function shall be called.

   191      *

   192      * @param aPtr - Pointer to this class instance.

   193      */

   194     static TInt IdleCallbackL( TAny* aPtr );

   195 

   196     /**

   197      * Updates whole area registry content to shared chunk. Called from

   198      * IdleCallbackL when feedback is enabled for this application.

   199      */

   200     void UpdateRegistryToChunkL();

   201 

   202     /**

   203      * Clears whole shared chunk so that there are no feedback areas at

   204      * all. Called from IdleCallbackL when feedback is disabled for this

   205      * application.

   206      */

   207     void ClearWholeChunkL();

   208 

   209     /**

   210      * This is a cleanup operation that releases a semaphore in case

   211      * a leave occurs while we have called Wait on the semaphore. 

   212      * Failing to release the semaphore (by calling "Signal" -function

   213      * on it) would lead to deadlock in the system.

   214      * @param aPtr - Pointer to RSemaphore.

   215      */

   216     static void CleanupSemaphore( TAny* aPtr );

   217 

   218 private: // data

   219 

   220     /**

   221      * Connection to window server click maker plugin.

   222      */

   223     RSoundPlugIn iClickPlugin;

   224     

   225     /**

   226      * Area registry in shared chunk between this process and

   227      * window server process.

   228      */

   229     RChunk iChunk;

   230     

   231     /**

   232      * Mutual exlusion with window server and other clients.

   233      */

   234     RSemaphore iSemaphore;

   235     

   236     /**

   237      * For knowing if we'll need to disconnect when this application

   238      * is closed.

   239      */    

   240     TBool iConnected;

   241     

   242     /**

   243      * For doing registry update as soon as possible, but not

   244      * immediately.

   245      * Own.  

   246      */

   247     CIdle* iIdle;

   248     

   249     /**

   250      * Access to local area registry

   251      * Not own.  

   252      */

   253     CTouchFeedbackImpl& iFeedback;

   254     

   255     /**

   256      * Client interface to tactile feedback server.

   257      * Own.

   258      */

   259     RTactileFeedback iFbClient;

   260     

   261     /**

   262      * Timer for continuous feedback timeout.

   263      * Own.

   264      */

   265     CPeriodic* iFeedbackTimer;

   266     

   267     /**

   268      * Client handle for checking continuous is not modified or stopped by

   269      * other clients that the one, which started it.

   270      */

   271     TUint32    iClientHandle;

   272     

   273     /**

   274      * Previous intensity value of an ongoing continuous feedback to prevent

   275      * unnecessary modify calls if there's no change in intensity. Also

   276      * new start call for ongoing feedback modifies the intensity if value

   277      * was changed.

   278      */

   279     TInt       iPreviousIntensity;

   280     };

   281 

   282 

   283 #endif //  C_TOUCHFEEDBACKCLIENT_H