/*

  CpsKernelIf.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:

*/

#ifndef __CPSKERNELIF_H__

#define __CPSKERNELIF_H__

//  - Includes ------------------------

//  - Namespace -----------------------

//  - Macros --------------------------

//  - Constants -----------------------

//  - External data -------------------

//  - Forward declarations ------------

class DCpsLddFactory;

class TCpsCallback;

//  - Data types ----------------------

//  - Class declarations --------------

/**

 * CPS interface for kernel side clients

 */

class DCpsKernelIf : public DBase

    {

public:

    /** 

     * Returns data stored into record (synchronous).

     *

     * @param  aGroup      The group ID which is accessed.

     * @param  aIndex      The index ID which is accessed.

     * @param  aLength     The size of data to be read from the beginning of record.

     * @param  aDataBuffer The pointer to data buffer that contains read data.

     * 

     * @return KErrNone or standard error code

     */

    IMPORT_C static TInt ReadRecord( TUint16 aGroup, TUint16 aIndex, TUint32 aLength, TDes8& aDataBuffer );

    /** 

     * Returns data stored into record (asynchronous).

     *

     * @param  aCb         The pointer to a CPS callback object.

     * @param  aGroup      The group ID which is accessed.

     * @param  aIndex      The index ID which is accessed.

     * @param  aLength     The size of data to be read from the beginning of record.

     * @param  aDataBuffer The pointer to data buffer that contains read data.

     */

    IMPORT_C static void ReadRecord( TCpsCallback* aCb, TUint16 aGroup, TUint16 aIndex, TUint32 aLength, TDes8& aDataBuffer );

    /**

     * Used to store data into record (synchronous).

     *

     * @param  aGroup      The group ID which is accessed.

     * @param  aIndex      The index ID which is accessed.

     * @param  aLength     The size of data to be written into record.

     * @param  aDataBuffer The pointer to data buffer that contains data.

     * 

     * @return KErrNone or standard error code

     */

    IMPORT_C static TInt WriteRecord( TUint16 aGroup, TUint16 aIndex, TUint32 aLength, const TDesC8& aDataBuffer );

    /**

     * Used to store data into record (asynchronous).

     *

     * @param  aCb         The pointer to a CPS callback object.

     * @param  aGroup      The group ID which is accessed.

     * @param  aIndex      The index ID which is accessed.

     * @param  aLength     The size of data to be written into record.

     * @param  aDataBuffer The pointer to data buffer that contains data.

     */

    IMPORT_C static void WriteRecord( TCpsCallback* aCb, TUint16 aGroup, TUint16 aIndex, TUint32 aLength, const TDesC8& aDataBuffer );

    /**

     * Used to remove existing record (synchronous).

     *

     * @param  aGroup      The group ID which is accessed.

     * @param  aIndex      The index ID which is accessed.

     * 

     * @return KErrNone or standard error code   

     */

    IMPORT_C static TInt RemoveRecord( TUint16 aGroup, TUint16 aIndex );

    /**

     * Used to remove existing record (asynchronous).

     *

     * @param  aCb         The pointer to a CPS callback object.

     * @param  aGroup      The group ID which is accessed.

     * @param  aIndex      The index ID which is accessed.   

     */

    IMPORT_C static void RemoveRecord( TCpsCallback* aCb, TUint16 aGroup, TUint16 aIndex );

    /**    

     * Used to remove all existing records from given group (synchronous).

     *

     * @param  aGroup      The group ID which is accessed.

     * 

     * @return KErrNone or standard error code

     */

    IMPORT_C static TInt RemoveAllRecords( TUint16 aGroup );

    /**    

     * Used to remove all existing records from given group (asynchronous).

     *

     * @param  aCb         The pointer to a CPS callback object.

     * @param  aGroup      The group ID which is accessed.  

     */

    IMPORT_C static void RemoveAllRecords( TCpsCallback* aCb, TUint16 aGroup );

    /**

     * Used to query size of existing record (synchronous).

     *

     * @param  aGroup      The group ID which is accessed.

     * @param  aIndex      The index ID which is accessed.

     * @param  aSize       CPS stores record size to this parameter.

     * 

     * @return KErrNone or standard error code     

     */

    IMPORT_C static TInt RecordSizeGet( TUint16 aGroup, TUint16 aIndex, TUint32& aSize );

    /**

     * Used to query amount of memory used by given group (synchronous).

     *

     * @param  aGroup      The group ID which is accessed.

     * @param  aSize       CPS stores amount of used memory by aGroup to this parameter.

     * 

     * @return KErrNone or standard error code   

     */

    IMPORT_C static TInt GroupSizeGet( TUint16 aGroup, TUint32& aSize );

    /**

     * Used to amount of available memory for given group (synchronous).

     *

     * @param  aGroup      The group ID which is accessed.

     * @param  aSize       CPS stores amount of available memory to this parameter.

     * 

     * @return KErrNone or standard error code     

     */

    IMPORT_C static TInt AvailableSizeGet( TUint16 aGroup, TUint32& aSize );

    /**

      * Cancels ongoing client request. 

      * 

      * @note Client's callback is called with KErrCancel status if request is removed successfully from the operation queue

      * 

      * @param  aCb         The pointer to a CPS callback object.

      */

    IMPORT_C static void CancelRequest( TCpsCallback* aCb );

    /**

     * CPS factory calls this to create kernel IF

     *

     * @note For CPS internal use only

     *

     * @param aFactoryObj   Factory object

     */

    static void CreateKernelInstance( DCpsLddFactory* aFactoryObj );

    /**

     * CPS factory calls this to delete kernel IF

     *

     * @note For CPS internal use only

     */

    static void DeleteKernelInstance();

private:

    /**

     * Used to query size of existing record (asynchronous).

     *

     * @param  aCb         The pointer to a CPS callback object.

     * @param  aGroup      The group ID which is accessed.

     * @param  aIndex      The index ID which is accessed.

     * @param  aSize       CPS stores record size to this parameter.     

     */

    static void RecordSizeGet( TCpsCallback* aCb, TUint16 aGroup, TUint16 aIndex, TUint32& aSize );

    /**

     * Used to query amount of memory used by given group (asynchronous).

     *

     * @param  aCb         The pointer to a CPS callback object.

     * @param  aGroup      The group ID which is accessed.

     * @param  aSize       CPS stores amount of used memory by aGroup to this parameter.   

     */

    static void GroupSizeGet( TCpsCallback* aCb, TUint16 aGroup, TUint32& aSize );

    /**

     * Used to amount of available memory for given group.

     *

     * @param  aCb         The pointer to a CPS callback object.

     * @param  aGroup      The group ID which is accessed.

     * @param  aSize       CPS stores amount of available memory to this parameter.     

     */

    static void AvailableSizeGet( TCpsCallback* aCb, TUint16 aGroup, TUint32& aSize );

    /**

     * Callback function for synchronous CPS kernel operation.

     * 

     * @ param aStatus KErrNone or standard error code

     * @ aArg Argument for callback

     */

    static void SyncOperationReady( TInt aStatus, TAny* aArg );

private:

    /**

     * Constructor

     */

    DCpsKernelIf();

    /**

     * Destructor

     */

    ~DCpsKernelIf();

private:

    /** Kernel IF object */

    static DCpsKernelIf* iKernelIf;

    /** Factory object */

    static DCpsLddFactory* iFactory;

    /** Callback for synchronous operations */

    TCpsCallback* iSyncCb;

    /** Semaphore for locking the synchronous interface */

    DSemaphore *iSyncLock;

    /** Synchronous operation result */

    TInt iSyncOpResult;

    };

/**

 * CPS asynchronous callback function 

 */

typedef void (*TCpsCbFn)( TInt aResult, TAny* aParam );

/**

 * CPS asynchronous callback DFC

 * The client must create one of these to be passed to each asynchronous call to kernel interface

 * The callback function is called in the context supplied by the client when creating an object of this kind (aQue)

 * The callback function takes as arguments the pin id and the state, so it can be common to all TGpioCallback

 */

class TCpsCallback : public TDfc

    {

public:

    inline TCpsCallback( TCpsCbFn aFn, TAny* aPtr, TDfcQue* aQue, TInt aPriority )

        : TDfc( DfcFunc, this, aQue, aPriority ), iParam( aPtr ), iCallback( aFn ) 

            {}

private:

    inline static void DfcFunc( TAny* aPtr )

        {

        TCpsCallback* pCb = (TCpsCallback*)aPtr;

        //Warning -- Possible use of null pointer

        //lint -e613

        pCb->iCallback( pCb->iResult, pCb->iParam );

        }

public:

    TInt iResult;

    TAny* iParam;

    TCpsCbFn iCallback;

    };

#endif /* __CPSKERNELIF_H__ */