diff -r 000000000000 -r 4e1aa6a622a0 devicesrv_plat/shared_data_api/inc/shareddataclient.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/devicesrv_plat/shared_data_api/inc/shareddataclient.h Tue Feb 02 00:53:00 2010 +0200 @@ -0,0 +1,198 @@ +/* +* 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 + +// 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