/*
  gptimer_chipset_api.h

  Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). 
  All rights reserved.

  This program and the accompanying materials are made available 
  under the terms of the Eclipse Public License v1.0 which accompanies 
  this distribution, and is available at 
  http://www.eclipse.org/legal/epl-v10.html

  Initial Contributors:
  Nokia Corporation - initial contribution.

  Contributors:
*/

/** @file
@brief General Purpose Timer Chipset API H

@publishedDeviceAbstraction
*/

#ifndef __GPTIMER_CHIPSET_API_H__
#define __GPTIMER_CHIPSET_API_H__


// Include files
#include <kern_priv.h>


/**
Pointer to a callback function for the GPT client to use

@note "Callback is executed in the DFC or ISR context"

@param TAny* pointer to a parameter the call back function may use
*/
typedef void (*GPTimerFn)(TAny*);



// Class declaration

/**
@brief GP timer class

 General Purpose Timer functionality for clients
*/
class GPTimer
    {
    public:
        /**
        constructor of a GPT object
        */
        IMPORT_C GPTimer();
          
          
        /**
        allocates a HW GPT

        @param aFunction A pointer to a callback function which is called 
               when the timer expires.
        @param aPtr A parameter of the callback function.

        @return returns KErrNone if there was no error or KErrInUse if no 
                HW GPT is available.

        @pre Pre-condition: HW GPT must be available
        */
        IMPORT_C TInt Open(GPTimerFn aFunction, TAny* aPtr);
          
          
        /**
        Releases a HW GPT

        @return Returns KErrNone if there was no error or KErrNotFound if 
                no HW GPT was allocated before.

        @pre Pre-condition: Open was called
        */
        IMPORT_C TInt Close();
          
          
        /**
        Starts a GPT in one-shot mode, the callback routine will be called in 
        interrupt context.

        @param aTime Timeout in microseconds.

        @return returns KErrNone if there was no error, KErrInUse if the timer is already active,
                        KErrNotFound if no HW GPT was allocated before.
        */
        IMPORT_C TInt OneShot(TUint aTime);



        /**
        Starts a GPT in one-shot mode, the callback routine will be called in client's DFC context.

        @param aTime Timeout in microseconds.
        @param aDfc client's DFC object.

        @return returns KErrNone if there was no error, KErrInUse if the timer is already active,
                        KErrArgument if aDfc is NULL, KErrNotFound if no HW GPT was allocated before.
        */
        IMPORT_C TInt OneShot(TUint aTime, TDfc& aDfc);



        /**
        Starts a GPT in periodic mode (the timer is restarted after it expired).
        The callback routine will be called in interrupt context.

        @param aTime Timeout in microseconds.

        @return returns KErrNone if there was no error, KErrInUse if the timer is already active,
                        KErrNotFound if no HW GPT was allocated before.
        */
        IMPORT_C TInt Periodic(TUint aTime);


        /**
        Starts a GPT in periodic mode (the timer is restarted after it expired).
        The callback routine will be called in client's DFC context.

        @param aTime Timeout in microseconds.
        @param aDfc client's DFC object.

        @return returns KErrNone if there was no error or KErrInUse if the timer is already active,
                        KErrArgument if aDfc is NULL, KErrNotFound if no HW GPT was allocated before.
        */
        IMPORT_C TInt Periodic(TUint aTime, TDfc& aDfc);


        /**
        Requests to cancel a GPT.

        @return Returns ETrue if the timer was actually cancelled or EFalse if the timer was not
                        cancelled because it was not running or the callback was already running.
        */
        IMPORT_C TBool Cancel();

        /**
        destructor of a GPT object
        */
        IMPORT_C ~GPTimer();
          
    private:
        /**
        stores aFunction parameter
        */
        GPTimerFn iFunction;


        /**
        stores aPtr parameter
        */
        TAny* iPtr;
        
        
        /**
        stores aTime parameter
        */
        TUint iTime;


        /**
        stores aDfc parameter
        */
        TDfc iDfc;
    };


#endif // __GPTIMER_CHIPSET_API_H__