/*
* Copyright (c) 2002 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 module offers an interface for applications to access other
*     applications' settings which are meant to have shared access.
*
*/


#ifndef SHARED_DATA_CLIENT_H
#define SHARED_DATA_CLIENT_H

// INCLUDES
#include <e32base.h>

// CONSTANTS

// reasons for panicing client thread

enum TSharedDataPanic
    {
    ESDBadRequest = 0,
    ESDNotAssigned = 1,
    ESDNotConnected = 2,
    ESDNotifyHandlerMissing = 3,
    ESDNoActiveScheduler = 4,
    ESDCannotChangeReadOnlySetting = 5
    };

_LIT( KSharedDataPanicCategory, "SharedData" );

// FORWARD DECLARATIONS
class CDosWrapper;

// CLASS DECLARATION

/**
*  RSharedDataClient API
*  -----------------------------------------------------------------------------
*  Applications use the subsystem via RSharedDataClient class. First, they need
*  to connect to the server by calling Connect() member function.
*
* ------------------------------------------------------------------------------
* RESERVE FILE SUPPORT
* ------------------------------------------------------------------------------
*
* This functionality has nothing to do with the rest of SharedData, but is
* implemented in SharedData server because it is one of the most commonly used
* servers. The idea is to support transaction-based delete operations to succeed
* in a full disk situation. SharedData server checks if the free disk space is
* below the given minimum treshold and if so, reduces the size of a reserve file
* to free up some disk space. No overhead is caused if there is enough free disk
* space already. Thus, unless the reserve file is somehow exhausted,
* the free disk space is guaranteed to be above the given parameter
* after this call. Of course, the parameter is limited to the maximum size of
* the reserve file that will be about 140kB. 
*
* There are two correct usage patterns represented below, other for synchronous
* delete operations and other for asynchronous ones.
* 
* Note! When the SharedData connection is closed, the server will 
* always assume that the reserve space is no longer required by the
* corresponding client.
*
* Usage pattern (synchronous delete operation):
* ------------------------------------------------------------------------------
* // iSharedDataClient is connected to the server here.
*
* iSharedDataClient.RequestFreeDiskSpaceLC( KDiskSpaceNeededForDelete );
*
* // Do the delete operation here, the code may leave.
*
* // Do NOT close the SharedData connection here nor delete the
* // RSharedDataClient object.
*
* CleanupStack::PopAndDestroy(); // cancels free disk space request
* ------------------------------------------------------------------------------
*
* Usage pattern (asynchronous delete operation):
* ------------------------------------------------------------------------------
* // iSharedDataClient is connected to the server here.
*
* iSharedDataClient.RequestFreeDiskSpace( KDiskSpaceNeededForDelete );
*
* // Start the asynchronous delete operation here
*
* // Do NOT close the SharedData connection here nor delete the
* // RSharedDataClient object.
*
* // When the asynchronous request has completed:
*
* iSharedDataClient.CancelFreeDiskSpaceRequest();
* ------------------------------------------------------------------------------
*/

class RSharedDataClient : public RSessionBase
    {

    public:

        /**
        * Constructor.
        *
        * Use this constructor if you don't use notify methods. User implemented
        * notify handler is set to NULL.
        */      
        IMPORT_C RSharedDataClient();

        /**
        * Starts the server if it's not already running. Creates a new session.
        * If a session is already established by the client, does nothing.
        *
        * @param aPriority priority for the active object handling notify
        *                  events. If you haven't given MSharedDataNotifyHandler
        *                  interface in constructor, this has no effect.
        *
        * @return Symbian OS standard error code
        */   
        IMPORT_C TInt Connect();
        
        /**
        * Closes the session. Cancels all notify requests, signals and incoming
        * notifications. Saves the changes if the shared data file was modified.
        * Remember to call this to a connected session in some point.
        *
        * If the UID is handled by a plugin instead of file, 
        * client might need to call Flush() explicitly before Close.
        * Check plugin documentation.
        */
        IMPORT_C void Close();

        
        /**
        * Full disk support for synchronous transactional delete operations.
        * If needed, frees up disk space so that it'll be above the given
        * minimum treshold.
        *
        * Use CleanupStack::PopAndDestroy() to cancel the request after the
        * delete operation.
        *
        * This method can leave only if CleanupStack::PushL() leaves.
        *
        * @param aAmount Requested minimum amount of free disk space in bytes.
        *                The max size of the reserve file will be around
        *                64k so there is no use to request higher amounts
        *                than that.
        */
        IMPORT_C void RequestFreeDiskSpaceLC( const TInt aAmount ) const;


        /**
        * Full disk support for asynchronous transactional delete operations.
        * If needed, frees up disk space so that it'll be above the given
        * minimum treshold.
        *
        * The user is responsible for calling CancelFreeDiskSpaceRequest()
        * after the asynchronous delete operation has been finished.
        *
        * @param aAmount Requested minimum amount of free disk space in bytes.
        *                The max size of the reserve file will be around
        *                64k so there is no use to request higher amounts
        *                than that.
        */
        IMPORT_C void RequestFreeDiskSpace( const TInt aAmount ) const;

        /**
        * Cancels the request made by calling RequestFreeDiskSpace().
        * In case of RequestFreeDiskSpaceLC(), CleanupStack will handle
        * calling this function.
        */
        IMPORT_C void CancelFreeDiskSpaceRequest() const;

    private:
        /**
        * Cleanup function
        */
        static void CleanupFreeDiskSpaceRequest( TAny* aAny );

    private: // data

        CDosWrapper* iDosWrapper;
    private: // friend classes
    };

#endif

// End of File