1 /*

     2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *     This module offers an interface for applications to access other

    16 *     applications' settings which are meant to have shared access.

    17 *

    18 */

    19 

    20 

    21 #ifndef SHARED_DATA_CLIENT_H

    22 #define SHARED_DATA_CLIENT_H

    23 

    24 // INCLUDES

    25 #include <e32base.h>

    26 

    27 // CONSTANTS

    28 

    29 // reasons for panicing client thread

    30 

    31 enum TSharedDataPanic

    32     {

    33     ESDBadRequest = 0,

    34     ESDNotAssigned = 1,

    35     ESDNotConnected = 2,

    36     ESDNotifyHandlerMissing = 3,

    37     ESDNoActiveScheduler = 4,

    38     ESDCannotChangeReadOnlySetting = 5

    39     };

    40 

    41 _LIT( KSharedDataPanicCategory, "SharedData" );

    42 

    43 // FORWARD DECLARATIONS

    44 class CDosWrapper;

    45 

    46 // CLASS DECLARATION

    47 

    48 /**

    49 *  RSharedDataClient API

    50 *  -----------------------------------------------------------------------------

    51 *  Applications use the subsystem via RSharedDataClient class. First, they need

    52 *  to connect to the server by calling Connect() member function.

    53 *

    54 * ------------------------------------------------------------------------------

    55 * RESERVE FILE SUPPORT

    56 * ------------------------------------------------------------------------------

    57 *

    58 * This functionality has nothing to do with the rest of SharedData, but is

    59 * implemented in SharedData server because it is one of the most commonly used

    60 * servers. The idea is to support transaction-based delete operations to succeed

    61 * in a full disk situation. SharedData server checks if the free disk space is

    62 * below the given minimum treshold and if so, reduces the size of a reserve file

    63 * to free up some disk space. No overhead is caused if there is enough free disk

    64 * space already. Thus, unless the reserve file is somehow exhausted,

    65 * the free disk space is guaranteed to be above the given parameter

    66 * after this call. Of course, the parameter is limited to the maximum size of

    67 * the reserve file that will be about 140kB. 

    68 *

    69 * There are two correct usage patterns represented below, other for synchronous

    70 * delete operations and other for asynchronous ones.

    71 * 

    72 * Note! When the SharedData connection is closed, the server will 

    73 * always assume that the reserve space is no longer required by the

    74 * corresponding client.

    75 *

    76 * Usage pattern (synchronous delete operation):

    77 * ------------------------------------------------------------------------------

    78 * // iSharedDataClient is connected to the server here.

    79 *

    80 * iSharedDataClient.RequestFreeDiskSpaceLC( KDiskSpaceNeededForDelete );

    81 *

    82 * // Do the delete operation here, the code may leave.

    83 *

    84 * // Do NOT close the SharedData connection here nor delete the

    85 * // RSharedDataClient object.

    86 *

    87 * CleanupStack::PopAndDestroy(); // cancels free disk space request

    88 * ------------------------------------------------------------------------------

    89 *

    90 * Usage pattern (asynchronous delete operation):

    91 * ------------------------------------------------------------------------------

    92 * // iSharedDataClient is connected to the server here.

    93 *

    94 * iSharedDataClient.RequestFreeDiskSpace( KDiskSpaceNeededForDelete );

    95 *

    96 * // Start the asynchronous delete operation here

    97 *

    98 * // Do NOT close the SharedData connection here nor delete the

    99 * // RSharedDataClient object.

   100 *

   101 * // When the asynchronous request has completed:

   102 *

   103 * iSharedDataClient.CancelFreeDiskSpaceRequest();

   104 * ------------------------------------------------------------------------------

   105 */

   106 

   107 class RSharedDataClient : public RSessionBase

   108     {

   109 

   110     public:

   111 

   112         /**

   113         * Constructor.

   114         *

   115         * Use this constructor if you don't use notify methods. User implemented

   116         * notify handler is set to NULL.

   117         */      

   118         IMPORT_C RSharedDataClient();

   119 

   120         /**

   121         * Starts the server if it's not already running. Creates a new session.

   122         * If a session is already established by the client, does nothing.

   123         *

   124         * @param aPriority priority for the active object handling notify

   125         *                  events. If you haven't given MSharedDataNotifyHandler

   126         *                  interface in constructor, this has no effect.

   127         *

   128         * @return Symbian OS standard error code

   129         */   

   130         IMPORT_C TInt Connect();

   131         

   132         /**

   133         * Closes the session. Cancels all notify requests, signals and incoming

   134         * notifications. Saves the changes if the shared data file was modified.

   135         * Remember to call this to a connected session in some point.

   136         *

   137         * If the UID is handled by a plugin instead of file, 

   138         * client might need to call Flush() explicitly before Close.

   139         * Check plugin documentation.

   140         */

   141         IMPORT_C void Close();

   142 

   143         

   144         /**

   145         * Full disk support for synchronous transactional delete operations.

   146         * If needed, frees up disk space so that it'll be above the given

   147         * minimum treshold.

   148         *

   149         * Use CleanupStack::PopAndDestroy() to cancel the request after the

   150         * delete operation.

   151         *

   152         * This method can leave only if CleanupStack::PushL() leaves.

   153         *

   154         * @param aAmount Requested minimum amount of free disk space in bytes.

   155         *                The max size of the reserve file will be around

   156         *                64k so there is no use to request higher amounts

   157         *                than that.

   158         */

   159         IMPORT_C void RequestFreeDiskSpaceLC( const TInt aAmount ) const;

   160 

   161 

   162         /**

   163         * Full disk support for asynchronous transactional delete operations.

   164         * If needed, frees up disk space so that it'll be above the given

   165         * minimum treshold.

   166         *

   167         * The user is responsible for calling CancelFreeDiskSpaceRequest()

   168         * after the asynchronous delete operation has been finished.

   169         *

   170         * @param aAmount Requested minimum amount of free disk space in bytes.

   171         *                The max size of the reserve file will be around

   172         *                64k so there is no use to request higher amounts

   173         *                than that.

   174         */

   175         IMPORT_C void RequestFreeDiskSpace( const TInt aAmount ) const;

   176 

   177         /**

   178         * Cancels the request made by calling RequestFreeDiskSpace().

   179         * In case of RequestFreeDiskSpaceLC(), CleanupStack will handle

   180         * calling this function.

   181         */

   182         IMPORT_C void CancelFreeDiskSpaceRequest() const;

   183 

   184     private:

   185         /**

   186         * Cleanup function

   187         */

   188         static void CleanupFreeDiskSpaceRequest( TAny* aAny );

   189 

   190     private: // data

   191 

   192         CDosWrapper* iDosWrapper;

   193     private: // friend classes

   194     };

   195 

   196 #endif

   197 

   198 // End of File