/*
* Copyright (c) 2008 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: Tactile feedback player plugin interface.
* Part of: Tactile Feedback.
*
*/
#ifndef C_TACTILEPLAYER_H
#define C_TACTILEPLAYER_H
#include <e32base.h>
#include <ecom/ecom.h>
#include <touchlogicalfeedback.h>
class CRepository;
/**
* Types of tactile players. This enumeration is used for listing the
* implementations of players of certain type.
* @since S60 5.2
*/
enum TTactilePlayerType
{
ETactilePlayerAny,
ETactilePlayerHaptics,
ETactilePlayerAudio
};
/**
* Tactile feedback player ECom plugin interface.
*
* There are two basic types of tactile players, haptics and audio
* players. Each player must follow the player type specific settings
* from Central Repository to play feedback in the specified level. If
* playing level for haptics or audio is set to zero, players of that type
* must not produce any feedback.
*
* UID for tactile feedback settings is:
* KCRUidTactileFeedback = 0x2000B494;
*
* Players are instantiated based on plugins' implementation UIDs, which
* are read from Central Repository by feedback resolver. Player types
* are differentiated by using word "Haptics" or "Audio" in default_data
* field in plugin's implementation info resource file.
*
* Preview functions for playing immediate and starting continuous feedback
* are ment to use for example in settings view to get feedback played with
* different level without actually changing the level in settings. It is
* feedback resolver's responsibility not to play regular feedbacks when
* preview functions are used.
*
* @lib tactilefeedbackresolver.lib
* @since S60 5.2
*/
class CTactilePlayer : public CBase
{
public:
/**
* Instantiates an object of this type.
*
* @since S60 5.2
* @param aImplementationUid - Implementation uid of the plugin
* to be created.
* @param aRepository - Reference to Central Repository, which is
* used for reading Tactile Feedback
* settings. CR Keys for Tactile Feedback are
* defined in tactilefeedbackdomaincrkeys.h
*
* @return Instance of feedback player plugin.
*/
static CTactilePlayer* NewL( TUid aImplementationUid,
CRepository& aRepository );
/**
* Destructor.
*/
IMPORT_C virtual ~CTactilePlayer();
/**
* Returns a list of available implementations for this
* interface.
*
* @since S60 5.2
* @param aType - Type of players to be listed.
* @param aImplInfoArray - Implementation information array of all
* available implementations.
*/
static void ListImplementationsL( TTactilePlayerType aType,
RImplInfoPtrArray& aImplInfoArray );
public:
/**
* Produces immediate physical feedback according to given
* logical feedback type.
*
* Haptics and audio players have onw level value, which is
* specified in Tactile Feedback settings in Central Repository.
* That value defines the strength of feedback produced by this function.
* When settings are changed, plugin implementation must change the
* playing level according to that value. If feedback level for this
* type of player in settings is set to zero, this function must not
* produce any feedback.
*
* @since S60 5.2
* @param aFeedback - The logical feedback type, which is used to
* select the physical response to feedback method.
* @return TInt KErrNone if successful, otherwise one of the other
* system-wide error codes.
*/
virtual TInt PlayFeedback( TTouchLogicalFeedback aFeedback ) = 0;
/**
* Starts continuous feedback according to given logical
* continuous feedback type. Continuous feedback is started with given
* intensity, which is a percentage value of maximum strength on current
* level. Ongoing continuous feedback can be modified using
* ModifyFeedback() to change intensity of feedback.
*
* Continuous feedback is stopped using StopFeedback().
*
* @since S60 5.2
* @param aFeedback - The logical feedback type of continuous feedback,
* which is used to select the physical response to
* continuous feedback method.
* @param aIntensity - The percentage value of continuous feedback's
* maximum strength.
* @return TInt KErrNone if successful, otherwise one of the other
* system-wide error codes.
* @return TInt KErrNotSupported if player doesn't support continuous
* feedback.
*/
IMPORT_C virtual TInt StartFeedback( TTouchContinuousFeedback aFeedback,
TInt aIntensity );
/**
* Modifies the intensity of continuous feedback.
*
* @since S60 5.2
* @param aIntensity - The percentage value of continuous feedback's
* intensity.
* @return TInt KErrNone if successful, otherwise one of the other
* system-wide error codes.
* @return TInt KErrNotSupported if player doesn't support continuous
* feedback.
*/
IMPORT_C virtual TInt ModifyFeedback( TInt aIntensity );
/**
* Stops continuous feedback.
*
* @since S60 5.2
*/
IMPORT_C virtual void StopFeedback();
/**
* Plugin's maximum feedback level, which defines the strength
* of played feedback. The amount of feedback levels is dependent on
* a plugin.
*
* Level values are used for playing preview of feedback.
*
* @since S60 5.2
* @return TInt KErrNone if successful, otherwise one of the other
* system-wide error codes.
*/
IMPORT_C virtual TInt MaxLevel();
/**
* Produces preview of feedback according to given locigal feedback
* type and given level value of feedback strength.
*
* @since S60 5.2
* @param aLevel - A value, which defines the strength of preview
* feedback. Preview level can be any positive
* value up to value of MaxLevel().
* @param aFeedback - The logical feedback type, which is used to
* select the physical response to feedback method.
* @return TInt KErrNone if successful, otherwise one of the other
* system-wide error codes.
* @return TInt KErrNotSupported if player doesn't support feedback
* preview.
*/
IMPORT_C virtual TInt PlayPreviewFeedback( TInt aLevel,
TTouchLogicalFeedback aFeedback );
/**
* Starts preview of continuous feedback according to given logical
* continuous feedback type and given level value of feedback strength.
* Preview of continuous feedback is started with given intensity,
* which is a percentage value of maximum strength in given level.
* Ongoing continuous feedback can be modified using ModifyFeedback()
* to change intensity of feedback.
*
* Preview of continuous feedback is stopped using StopFeedback().
*
* @since S60 5.2
* @param aLevel - A value, which defines the strength of preview
* feedback. Preview level can be any positive
* value between zero and MaxLevel().
* @param aFeedback - The logical feedback type of continuous feedback,
* which is used to select the physical response to
* continuous feedback method.
* @param aIntensity - The percentage value of continuous feedback's
* maximum strength.
* @return TInt KErrNone if successful, otherwise one of the other
* system-wide error codes.
* @return TInt KErrNotSupported if player doesn't support preview
* for continuous feedback.
*/
IMPORT_C virtual TInt StartPreviewFeedback( TInt aLevel,
TTouchContinuousFeedback aFeedback,
TInt aIntensity );
/**
* Stops preview of continuous feedback. Player must set the original
* level value back in this function.
*
* @since S60 5.2
*/
IMPORT_C virtual void StopPreviewFeedback();
private:
// Unique instance identifier key.
TUid iDtor_ID_Key;
};
#endif // C_TACTILEPLAYER_H