--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/tactilefeedback/tactilefeedbackresolver/inc/tactileplayer.h Thu Dec 17 08:53:38 2009 +0200
@@ -0,0 +1,242 @@
+/*
+* 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