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




#ifndef C_ALFBATCHBUFFER_H
#define C_ALFBATCHBUFFER_H
 
#include <e32base.h>

class CAlfEnv;

/**
 * Auto flush modes
 * @see SetAutoFlushMode, AutoFlushMode
 */
enum TAlfAutoFlushMode
    {
    // Batch buffer is flushed automatically by scheduler = default
    EAlfAutoFlushDeferred = 0, 
    
    // Every command is flushed instantly i.e. no batching
    EAlfAutoFlushInstant, 
    
    // Batch buffer is used but only flushed with 
    // #1 manual call to FlushBatchBuffer
    // #2 max buffer limit is reached
    // #3 OOM when expanding the batch buffer
    EAlfAutoFlushOnlyForced 
    };
 
/**
 * Size modes
 * @see SetMaxBatchBufferSize
 */
const TInt KAlfBatchBufferSizeLimitToSystemDefault = 0;
const TInt KAlfBatchBufferSizeNoLimit = -1;


/**
 * Info types
 * @see GetBatchBufferInfo
 */
enum TAlfBatchBufferInfoType
    {
    // Default buffer size which is used if not overridden.
    // 100 <= DefaultBufferSize <= 10000 depending on the product.
    EAlfBatchBufferInfoDefaultBufferSize,
    
    // User defined max size. See SetMaxBatchBufferSize for the values.
    // If user defined: MaxSize >= DefaultBufferSize
    EAlfBatchBufferInfoMaxSize, 
     
    // Currently allocated buffer size.
    // If not limited: DefaultBufferSize <= CurrentlyAllocated
    // If limited: DefaultBufferSize <= CurrentlyAllocated <= MaxSize
    EAlfBatchBufferInfoCurrentlyAllocated,
    
    // Size which the commands use from the buffer. 
    // Always: CommandsAllocate <= CurrentlyAllocated 
    EAlfBatchBufferInfoCommandsAllocate
    };

/**
 *  API to control the command batch buffer
 *
 *  @code
 *   CAlfBatchBuffer& batchBuffer = iEnv->BatchBufferHandler();
 *
 *   // Get the batch buffer max size in bytes
 *   const TInt maxSize = batchBuffer.GetBatchBufferInfo( EAlfBatchBufferInfoMaxSize );
 *
 *   // Flush manually
 *   batchBuffer.FlushBatchBuffer();
 *  @endcode
 *
 *  @lib alfclient.lib
 *  @since S60 v5.0
 */
NONSHARABLE_CLASS( CAlfBatchBuffer ): public CBase
    {
    
public:

    /**
     * Two-phased constructor.
     * @param aEnv Environment class
     * @return New instance. Ownership returned.
     */
    static CAlfBatchBuffer* NewL( CAlfEnv& aEnv );


    /**
    * Destructor.
    */
    virtual ~CAlfBatchBuffer();

    /**
     * Sets the automatic flush mode.
     *
     * @param aAutoFlushMode - see TAutoFlushMode
     */    
    IMPORT_C void SetAutoFlushMode( TAlfAutoFlushMode aAutoFlushMode );
    
    /**
     * Returns the automatic flush mode.
     *
     * @return Auto-flush mode - see TAlfAutoFlushMode.
     */         
    IMPORT_C TAlfAutoFlushMode AutoFlushMode() const;
    
    /**
     * Flushes the batch buffer manually.
     *
     * Even on error case, the buffer is emptied.
     *
     * @return Symbian OS error code.
     */
    IMPORT_C TInt FlushBatchBuffer();
    
    /**
     * Controls the batch buffer size. 
     *
     * When the buffer reaches the max size, it will be automatically flushed
     * if mode not equals EAutoFlushNever.
     *
     * The buffer will be also flushed, if expanding the buffer fails in OOM.
     *
     * @param aBufferSize 
     *        >0 Batch buffer size in bytes. If < default size, 
     *          the default size will be used.
     *        KAlfBatchBufferSizeLimitToSystemDefault uses the default size.
     *        KAlfBatchBufferSizeNoLimit re-allocates a bigger 
     *          buffer when needed until OOM.
     */
    IMPORT_C void SetMaxBatchBufferSize( TInt aBufferSize );
    
    /**
     * Get info about the batch buffer. 
     *
     * @param aBufferInfoType See TAlfBatchBufferInfoType
     *
     * @return Value in bytes.
     */
    IMPORT_C TInt GetBatchBufferInfo( TAlfBatchBufferInfoType aBufferInfoType ) const;
    
private:

    CAlfBatchBuffer();
    void ConstructL( CAlfEnv& aEnv );
private: // data

    struct TBatchBufferData;
    TBatchBufferData* iData;
    };

#endif // C_ALFBATCHBUFFER_H