/*
* Copyright (c) 2006-2009 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:
* This file contains the following sections:
* - Command definitions for HWRM Vibra plugin API
* - Command parameter definitions for HWRM Vibra plugin API
* - Response parameter definitions for HWRM Vibra plugin API
*
*/




/**
 @file
 @publishedPartner
 @released
*/


#ifndef HWRMVIBRACOMMANDS_H
#define HWRMVIBRACOMMANDS_H

// Include plugin service so that including only this header is necessary to use Vibra plugin API.
#include <hwrm/hwrmpluginservice.h>

// CONSTANTS

// Identifies the ECom implementation to be used.
_LIT8(KHWRMVibraApiEComMatch, "HWRMVibra");


/**
*  Plugin interface class just encapsulates the Vibra command enumerations.
*  Responsible for defining the command IDs for each message.
*/
namespace HWRMVibraCommand
    {
    /**
    * Data structure used to pass vibra intensity and duration.
    * Used in EPulseVibraCmdId command.
	*
	* @publishedPartner
	* @released
    */ 
    struct TVibraData
   	    {
   	    // Duration of vibration in milliseconds. 
        TUint iDuration;
   	    // Intensity of vibration. 
   	    TInt8 iIntensity;
   	    };

    // typedef'd package of TInt containing the vibra command*/
    typedef TPckgBuf<TInt> TStartVibraCmdDataPackage;
    
       
    // Data packages for pulse command
    typedef TPckgBuf<TVibraData> TPulseVibraCmdDataPackage;

   
    /** typedef'd package of TInt containing the error code response. */
    typedef TPckgBuf<TInt> TErrorCodeResponsePackage;

    /**
    * Command definitions
    * All commands contain a command id and a set of parameters. The command ids
    * are defined first and after that parameters for each command.
    *
    * This interface is asynchronous. A command is interpreted of being completed
    * after a response for that command is received.
    *
    * The field input means the parameter for the command.
    * The field output means the parameter for the response.
	*
	* @publishedPartner
	* @released
    */
    enum TVibraCmd
        {
        /**
        * No command. May be used for sanity checks, but 
        * never as an actual command ID.
        *
        * input    None   
        * output   None   
        */
        ENoCommandId = 2000,
        
        /**
        * Start vibra. 
        *
        *
        * input    TStartVibraCmdDataPackage   Intensity  
        *    Intensity of the vibra in decimal is -100 to 100,
        *    which shows the percentage of the vibra motor full
        *    safe rotation speed. When intensity is negative, 
        *    the vibra motor rotates in the negative direction.
        *    When intensity is positive, the vibra motor rotates
        *    in the positive direction. 
        *    Value 0 effectively stops the vibra.
        *    Plugin should map intensity to such values that high or 
        *    low intensities never damage the device even
        *    if used for extended periods of time.
        * output   TErrorCodeResponsePackage   Error code
        *    KErrNone if operation succeeds.  
        *    KErrNotSupported if device doesn't support user-defined vibra intensity. 
        *    KErrArgument if intensity is outside allowed range.
        *    KErrGeneral if there is any problem.
        */
        EStartVibraCmdId,
        
        /**
        * Start vibra with device default intensity.
        *
        * input    None   
        * output   TErrorCodeResponsePackage   Error code     
        *    KErrNone if operation succeeds.   
        *    KErrGeneral if there is any problem.
        */
        EStartVibraWithDefaultSettingsCmdId,

        /**
        * Stop vibra. 
        *
        * input    None   
        * output   TErrorCodeResponsePackage   Error code     
        *    KErrNone if operation succeeds.   
        *    KErrGeneral if there is any problem.
        */
        EStopVibraCmdId,
        
        /**
        * Pulse vibra. Start and stop of vibration must be carried
        * out internally within plugin or underlying implementation.
        * If there is vibration ongoing when pulse command is sent,
        * intensity must be set according to pulse command intensity 
        * and when specified pulse duration has expired, interrupted
        * intensity must be restored. Ideally vibrations with varying 
        * intensity are observable althoug they would overlap.
        *
        * input    TPulseVibraCmdDataPackage   iIntensity
        *    Intensity of the vibra in decimal is 1 to 100,
        *    which shows the percentage of the vibra motor full
        *    safe rotation speed.
        *    Plugin should map intensity to such values that high or 
        *    low intensities never damage the device even
        *    if used for extended periods of time.
        * input    TPulseVibraCmdDataPackage   iDuration
        *    Duration of the vibra in milliseconds
        * output   TErrorCodeResponsePackage   Error code     
        *    KErrNone if operation succeeds.   
        *    KErrNotSupported if device doesn't support user-defined vibra intensity.
        *    KErrArgument if intensity or duration is outside allowed range.
        *    KErrGeneral if there is any problem.
        */
        EPulseVibraCmdId
        };
    }

#endif      // HWRMVIBRACOMMANDS_H   
            
// End of File