1 /*

     2 * Copyright (c) 2007 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:   API to control the command batch buffer

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef C_ALFBATCHBUFFER_H

    22 #define C_ALFBATCHBUFFER_H

    23  

    24 #include <e32base.h>

    25 

    26 class CAlfEnv;

    27 

    28 /**

    29  * Auto flush modes

    30  * @see SetAutoFlushMode, AutoFlushMode

    31  */

    32 enum TAlfAutoFlushMode

    33     {

    34     // Batch buffer is flushed automatically by scheduler = default

    35     EAlfAutoFlushDeferred = 0, 

    36     

    37     // Every command is flushed instantly i.e. no batching

    38     EAlfAutoFlushInstant, 

    39     

    40     // Batch buffer is used but only flushed with 

    41     // #1 manual call to FlushBatchBuffer

    42     // #2 max buffer limit is reached

    43     // #3 OOM when expanding the batch buffer

    44     EAlfAutoFlushOnlyForced 

    45     };

    46  

    47 /**

    48  * Size modes

    49  * @see SetMaxBatchBufferSize

    50  */

    51 const TInt KAlfBatchBufferSizeLimitToSystemDefault = 0;

    52 const TInt KAlfBatchBufferSizeNoLimit = -1;

    53 

    54 

    55 /**

    56  * Info types

    57  * @see GetBatchBufferInfo

    58  */

    59 enum TAlfBatchBufferInfoType

    60     {

    61     // Default buffer size which is used if not overridden.

    62     // 100 <= DefaultBufferSize <= 10000 depending on the product.

    63     EAlfBatchBufferInfoDefaultBufferSize,

    64     

    65     // User defined max size. See SetMaxBatchBufferSize for the values.

    66     // If user defined: MaxSize >= DefaultBufferSize

    67     EAlfBatchBufferInfoMaxSize, 

    68      

    69     // Currently allocated buffer size.

    70     // If not limited: DefaultBufferSize <= CurrentlyAllocated

    71     // If limited: DefaultBufferSize <= CurrentlyAllocated <= MaxSize

    72     EAlfBatchBufferInfoCurrentlyAllocated,

    73     

    74     // Size which the commands use from the buffer. 

    75     // Always: CommandsAllocate <= CurrentlyAllocated 

    76     EAlfBatchBufferInfoCommandsAllocate

    77     };

    78 

    79 /**

    80  *  API to control the command batch buffer

    81  *

    82  *  @code

    83  *   CAlfBatchBuffer& batchBuffer = iEnv->BatchBufferHandler();

    84  *

    85  *   // Get the batch buffer max size in bytes

    86  *   const TInt maxSize = batchBuffer.GetBatchBufferInfo( EAlfBatchBufferInfoMaxSize );

    87  *

    88  *   // Flush manually

    89  *   batchBuffer.FlushBatchBuffer();

    90  *  @endcode

    91  *

    92  *  @lib alfclient.lib

    93  *  @since S60 v5.0

    94  */

    95 NONSHARABLE_CLASS( CAlfBatchBuffer ): public CBase

    96     {

    97     

    98 public:

    99 

   100     /**

   101      * Two-phased constructor.

   102      * @param aEnv Environment class

   103      * @return New instance. Ownership returned.

   104      */

   105     static CAlfBatchBuffer* NewL( CAlfEnv& aEnv );

   106 

   107 

   108     /**

   109     * Destructor.

   110     */

   111     virtual ~CAlfBatchBuffer();

   112 

   113     /**

   114      * Sets the automatic flush mode.

   115      *

   116      * @param aAutoFlushMode - see TAutoFlushMode

   117      */    

   118     IMPORT_C void SetAutoFlushMode( TAlfAutoFlushMode aAutoFlushMode );

   119     

   120     /**

   121      * Returns the automatic flush mode.

   122      *

   123      * @return Auto-flush mode - see TAlfAutoFlushMode.

   124      */         

   125     IMPORT_C TAlfAutoFlushMode AutoFlushMode() const;

   126     

   127     /**

   128      * Flushes the batch buffer manually.

   129      *

   130      * Even on error case, the buffer is emptied.

   131      *

   132      * @return Symbian OS error code.

   133      */

   134     IMPORT_C TInt FlushBatchBuffer();

   135     

   136     /**

   137      * Controls the batch buffer size. 

   138      *

   139      * When the buffer reaches the max size, it will be automatically flushed

   140      * if mode not equals EAutoFlushNever.

   141      *

   142      * The buffer will be also flushed, if expanding the buffer fails in OOM.

   143      *

   144      * @param aBufferSize 

   145      *        >0 Batch buffer size in bytes. If < default size, 

   146      *          the default size will be used.

   147      *        KAlfBatchBufferSizeLimitToSystemDefault uses the default size.

   148      *        KAlfBatchBufferSizeNoLimit re-allocates a bigger 

   149      *          buffer when needed until OOM.

   150      */

   151     IMPORT_C void SetMaxBatchBufferSize( TInt aBufferSize );

   152     

   153     /**

   154      * Get info about the batch buffer. 

   155      *

   156      * @param aBufferInfoType See TAlfBatchBufferInfoType

   157      *

   158      * @return Value in bytes.

   159      */

   160     IMPORT_C TInt GetBatchBufferInfo( TAlfBatchBufferInfoType aBufferInfoType ) const;

   161     

   162 private:

   163 

   164     CAlfBatchBuffer();

   165     void ConstructL( CAlfEnv& aEnv );

   166 private: // data

   167 

   168     struct TBatchBufferData;

   169     TBatchBufferData* iData;

   170     };

   171 

   172 #endif // C_ALFBATCHBUFFER_H