1.1 --- a/epoc32/include/hwrmvibra.h Wed Mar 31 12:27:01 2010 +0100
1.2 +++ b/epoc32/include/hwrmvibra.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -1,22 +1,22 @@
1.4 /*
1.5 -* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.7 * All rights reserved.
1.8 * This component and the accompanying materials are made available
1.9 -* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
1.10 +* under the terms of "Eclipse Public License v1.0"
1.11 * which accompanies this distribution, and is available
1.12 -* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.13 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.14 *
1.15 * Initial Contributors:
1.16 * Nokia Corporation - initial contribution.
1.17 *
1.18 * Contributors:
1.19 *
1.20 -* Description: This file contains the header of the
1.21 -* CHWRMVibra class.
1.22 +* Description:
1.23 *
1.24 */
1.25
1.26
1.27 +
1.28 #ifndef HWRMVIBRA_H
1.29 #define HWRMVIBRA_H
1.30
1.31 @@ -28,27 +28,42 @@
1.32 /**
1.33 * Minimum allowed intensity setting for vibra. When intensity is negative,
1.34 * the vibra motor rotates in the negative direction.
1.35 +
1.36 +*
1.37 +* @publishedAll
1.38 +* @released
1.39 */
1.40 const TInt KHWRMVibraMinIntensity = -100;
1.41
1.42 /**
1.43 * Minimum allowed intensity setting for vibra pulse.
1.44 +*
1.45 +* @publishedAll
1.46 +* @released
1.47 */
1.48 const TInt KHWRMVibraMinPulseIntensity = 1;
1.49
1.50 +
1.51 /**
1.52 * Maximum allowed intensity setting for vibra. When intensity is positive,
1.53 * the vibra motor rotates in the positive direction. Value 0 effectively
1.54 * stops the vibra.
1.55 +
1.56 +* @publishedAll
1.57 +* @released
1.58 */
1.59 const TInt KHWRMVibraMaxIntensity = 100;
1.60
1.61 /**
1.62 * Maximum allowed duration value in milliseconds. Maximum vibrating time
1.63 * supported by device is declared in KVibraCtrlMaxTime cenrep-key.
1.64 +
1.65 *
1.66 * Note that duration probably has device specific
1.67 * maximum duration that is much lower.
1.68 +*
1.69 +* @publishedAll
1.70 +* @released
1.71 */
1.72 const TInt KHWRMVibraMaxDuration = (KMaxTInt / 1000) - 1;
1.73
1.74 @@ -56,15 +71,16 @@
1.75 * KHWRMVibraInfiniteDuration specifies, that vibrating should continue maximum
1.76 * vibrating time supported by device if vibrating is not explicitly stopped.
1.77 *
1.78 +*
1.79 +* @publishedAll
1.80 +* @released
1.81 */
1.82 const TInt KHWRMVibraInfiniteDuration = 0;
1.83
1.84 -// FORWARD DECLARATIONS
1.85 +
1.86 class MHWRMVibraObserver;
1.87 class MHWRMVibraFeedbackObserver;
1.88
1.89 -// CLASS DECLARATIONS
1.90 -
1.91 /**
1.92 * The class used to control the device vibra.
1.93 *
1.94 @@ -73,19 +89,17 @@
1.95 * of the vibration feature in the user profile and the current status of the vibra.
1.96 *
1.97 * The type of HW Resource Manager Vibra API is a synchronous method call meaning
1.98 -* the method call will block the client application. However, e.g. StartVibraL methods do
1.99 -* return right after device vibration has successfully been started. Callback is intended only
1.100 -* for observing vibra and feedback on/off changes. The API is meant for all
1.101 +* the method call will block the client application. The API is meant for all
1.102 * applications which need to control the device vibra.
1.103 *
1.104 -* The API consist of the classes CHWRMVibra, MHWRMVibraObserver and MHWRMVibraFeedbackObserver.
1.105 -* If the client requires up-to-date status information, it should also provide callback pointer
1.106 -* of the MHWRMVibraObserver implementing class for the NewL-method and explicitly set feedback observer.
1.107 +* The API consist of the classes CHWRMVibra and MHWRMVibraObserver. If the client
1.108 +* requires up-to-date status information, it should also provide callback pointer
1.109 +* of the MHWRMVibraObserver implementing class for the NewL-method.
1.110 *
1.111 * Usage:
1.112 *
1.113 * @code
1.114 -* #include <HWRMVibra.h> // link against HWRMVibraClient.lib
1.115 +* #include <hwrmvibra.h>
1.116 *
1.117 * // A CHWRMVibra instance can be created by using NewL() or NewLC() methods.
1.118 * // Up-to-date status information not required, no callbacks.
1.119 @@ -99,8 +113,8 @@
1.120 * delete vibra;
1.121 * @endcode
1.122 *
1.123 -* @lib HWRMVIBRACLIENT.DLL
1.124 -* @since S60 3.0
1.125 +* @publishedAll
1.126 +* @released
1.127 */
1.128 class CHWRMVibra : public CBase
1.129 {
1.130 @@ -110,9 +124,18 @@
1.131 */
1.132 enum TVibraModeState
1.133 {
1.134 - EVibraModeUnknown = 0, ///< Not initialized yet or there is an error condion.
1.135 - EVibraModeON, ///< Vibration setting in the user profile is on.
1.136 - EVibraModeOFF ///< Vibration setting in the user profile is off.
1.137 + /**
1.138 + Not initialized yet or there is an error condion.
1.139 + */
1.140 + EVibraModeUnknown = 0,
1.141 + /**
1.142 + Vibration setting in the user profile is on.
1.143 + */
1.144 + EVibraModeON,
1.145 + /**
1.146 + Vibration setting in the user profile is off.
1.147 + */
1.148 + EVibraModeOFF
1.149 };
1.150
1.151 /**
1.152 @@ -120,14 +143,23 @@
1.153 */
1.154 enum TVibraStatus
1.155 {
1.156 - EVibraStatusUnknown = 0, ///< Vibra is not initialized yet or status is uncertain
1.157 - ///< because of an error condition.
1.158 - EVibraStatusNotAllowed, ///< Vibra is set off in the user profile or some
1.159 - ///< application is specifically blocking vibra.
1.160 - EVibraStatusStopped, ///< Vibra is stopped.
1.161 - EVibraStatusOn ///< Vibra is on.
1.162 + /**
1.163 + Vibra is not initialized yet or status is uncertain because of an error condition.
1.164 + */
1.165 + EVibraStatusUnknown = 0,
1.166 + /**
1.167 + Vibra is set off in the user profile or some application is specifically blocking vibra.
1.168 + */
1.169 + EVibraStatusNotAllowed,
1.170 + /**
1.171 + Vibra is stopped.
1.172 + */
1.173 + EVibraStatusStopped,
1.174 + /**
1.175 + Vibra is on.
1.176 + */
1.177 + EVibraStatusOn
1.178 };
1.179 -
1.180 /**
1.181 * Tactile feedback vibration setting in the user profile.
1.182 */
1.183 @@ -136,10 +168,8 @@
1.184 EVibraFeedbackModeUnknown = 0, ///< Not initialized yet or there is an error condion.
1.185 EVibraFeedbackModeON, ///< Feedback vibration setting in the user profile is on.
1.186 EVibraFeedbackModeOFF ///< Feedback vibration setting in the user profile is off.
1.187 - };
1.188 -
1.189 - public: // Constructors
1.190 -
1.191 + };
1.192 + public:
1.193 /**
1.194 * Two-phased constructor.
1.195 *
1.196 @@ -190,13 +220,11 @@
1.197
1.198 /**
1.199 * Reserves vibration feature exclusively for this client.
1.200 - * A higher priority (not process or thread priority, but the priority defined
1.201 - * in the internal vibra policy of the HW Resource Manager) client may cause
1.202 - * lower priority client reservation to be temporarily suspended. Commands
1.203 - * can still be issued in suspended state, but they will not be acted upon
1.204 - * unless suspension is lifted within specified duration.
1.205 - * The suspended client will not get any notification about suspension and
1.206 - * neither from resumption of reservation.
1.207 + * A higher priority client may cause lower priority client reservation
1.208 + * to be temporarily suspended. Commands can still be issued in suspended
1.209 + * state, but they will not be acted upon unless suspension is lifted
1.210 + * within specified duration.
1.211 + * The suspended client will not get any notification about suspension.
1.212 * If vibra is already reserved by a higher or equal priority application,
1.213 * reserving will still succeed, but reservation is immediately suspended.
1.214 *
1.215 @@ -212,13 +240,11 @@
1.216
1.217 /**
1.218 * Reserves vibration feature exclusively for this client.
1.219 - * A higher priority (not process or thread priority, but the priority defined
1.220 - * in the internal vibra policy of the HW Resource Manager) client may cause
1.221 - * lower priority client reservation to be temporarily suspended. Commands
1.222 - * can still be issued in suspended state, but they will not be acted upon
1.223 - * unless suspension is lifted within specified duration.
1.224 - * The suspended client will not get any notification about suspension and
1.225 - * neither from resumption of reservation.
1.226 + * A higher priority client may cause lower priority client reservation
1.227 + * to be temporarily suspended. Commands can still be issued in suspended
1.228 + * state, but they will not be acted upon unless suspension is lifted
1.229 + * within specified duration.
1.230 + * The suspended client will not get any notification about suspension.
1.231 * If vibra is already reserved by a higher or equal priority application,
1.232 * reserving will still succeed, but reservation is immediately suspended.
1.233 *
1.234 @@ -246,7 +272,7 @@
1.235 * ETrue. A client is considered trusted if it has nonstandard
1.236 * priority defined in the internal vibra policy of the
1.237 * HW Resource Manager. A client can be defined trusted
1.238 - * only by S60 or a product.
1.239 + * only by a product.
1.240 *
1.241 * @leave KErrAccessDenied Parameter aForceNoCCoeEnv is ETrue and client is not
1.242 * trusted.
1.243 @@ -285,10 +311,10 @@
1.244 * the duration parameter is greater than the limit.
1.245 *
1.246 * @param aDuration Duration of the vibration measured in milliseconds.
1.247 - * A value of KHWRMVibraInfiniteDuration specifies that
1.248 - * the vibration should continue indefinetely and should
1.249 - * be stopped with a call to StopVibraL. Duration
1.250 - * usually has device specific maximum value.
1.251 + * A value of 0 specifies that the vibration should
1.252 + * continue indefinetely and should be stopped with a
1.253 + * call to StopVibraL. Duration can have maximum value
1.254 + * of KHWRMVibraMaxDuration.
1.255 *
1.256 * @leave KErrArgument Duration is invalid.
1.257 * @leave KErrAccessDenied Vibration setting in the user profile is not set.
1.258 @@ -324,12 +350,11 @@
1.259 * the duration parameter is greater than the limit.
1.260 *
1.261 * @param aDuration Duration of the vibration measured in milliseconds.
1.262 - * A value of KHWRMVibraInfiniteDuration specifies that
1.263 - * the vibration should continue indefinetely and should
1.264 - * be stopped with a call to StopVibraL. Duration
1.265 - * usually has device specific maximum value.
1.266 - * @param aIntensity Intensity of the vibra in decimal is KHWRMVibraMinIntensity
1.267 - * to KHWRMVibraMaxIntensity,
1.268 + * A value of 0 specifies that the vibration should
1.269 + * continue indefinitly and should be stopped with a
1.270 + * call to StopVibraL. Duration can have maximum value
1.271 + * of KHWRMVibraMaxDuration.
1.272 + * @param aIntensity Intensity of the vibra in decimal is -100 to 100,
1.273 * which shows the percentage of the vibra motor full
1.274 * rotation speed. When intensity is negative,
1.275 * the vibra motor rotates in the negative direction.
1.276 @@ -507,9 +532,9 @@
1.277 * NOTE: The device might have hardware-imposed limits
1.278 * on supported vibra intensity values, so actual
1.279 * effect might vary between different hardware.
1.280 - *
1.281 * @leave KErrNotSupported The device doesn't support user-defined
1.282 * vibra intensity.
1.283 + *
1.284 * @leave KErrArgument One of the parameters is out of range.
1.285 * @leave KErrAccessDenied Vibration setting in the user profile is not set
1.286 * or client is not privileged to use pulse feature.
1.287 @@ -561,7 +586,7 @@
1.288 *
1.289 * @code
1.290 * // INCLUDES
1.291 -* #include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
1.292 +* #include <hwrmvibra.h> // Link against HWRMVibraClient.lib.
1.293 *
1.294 * class CTest : public CBase,
1.295 * public MHWRMVibraObserver
1.296 @@ -608,7 +633,8 @@
1.297 * }
1.298 * @endcode
1.299 *
1.300 -* @since S60 3.0
1.301 +* @publishedAll
1.302 +* @released
1.303 */
1.304 class MHWRMVibraObserver
1.305 {
1.306 @@ -634,72 +660,9 @@
1.307 };
1.308
1.309 /**
1.310 -* A callback interface for tactile feedback vibra mode reporting.
1.311 *
1.312 -* If the client requires up-to-date status information, the client needs
1.313 -* to derive a class from the MHWRMVibraFeedbackObserver interface and implement
1.314 -* the VibraFeedbackModeChanged() method. In order to register for callback, client
1.315 -* needs to call SetFeedbackObserver-method.
1.316 -*
1.317 -* A callback object header example:
1.318 -*
1.319 -* @code
1.320 -* // INCLUDES
1.321 -* #include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
1.322 -*
1.323 -* class CTest : public CBase,
1.324 -* public MHWRMVibraFeedbackObserver
1.325 -* {
1.326 -* public:
1.327 -* CTest();
1.328 -* ~CTest();
1.329 -*
1.330 -* void ConstructL();
1.331 -* static CTest* NewL();
1.332 -*
1.333 -* // from MHWRMVibraFeedbackObserver
1.334 -* virtual void VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode);
1.335 -*
1.336 -* private:
1.337 -* CHWRMVibra* iVibra;
1.338 -* };
1.339 -* @endcode
1.340 -*
1.341 -* A callback method implementation example:
1.342 -*
1.343 -* @code
1.344 -*
1.345 -* #include <HWRMVibra.h> // link against HWRMVibraClient.lib
1.346 -*
1.347 -* // A CHWRMVibra instance can be created by using NewL() or NewLC() methods.
1.348 -* CHWRMVibra* vibra = CHWRMVibra::NewL();
1.349 -*
1.350 -* // Request notification of feedback setting change
1.351 -* vibra->SetFeedbackObserver(this);
1.352 -*
1.353 -* // To clean up, delete the created object:
1.354 -* delete vibra;
1.355 -*
1.356 -* void CTest::VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode)
1.357 -* {
1.358 -* switch ( aMode )
1.359 -* {
1.360 -* case CHWRMVibra::EVibraFeedbackModeUnknown:
1.361 -* RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeUnknown"));
1.362 -* break;
1.363 -* case CHWRMVibra::EVibraFeedbackModeON:
1.364 -* RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeON"));
1.365 -* break;
1.366 -* case CHWRMVibra::EVibraFeedbackModeOFF:
1.367 -* RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeOFF"));
1.368 -* break;
1.369 -* default:
1.370 -* break;
1.371 -* }
1.372 -* }
1.373 -* @endcode
1.374 -*
1.375 -* @since S60 5.0
1.376 +* @publishedAll
1.377 +* @released
1.378 */
1.379 class MHWRMVibraFeedbackObserver
1.380 {