/*

* 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:  This class handles dynamic name-value pair storing.

*

*/

#ifndef C_XMPPSETTINGSAPI_H

#define C_XMPPSETTINGSAPI_H

#include <e32base.h>

class CRepository;

class CXmppSettingsRecord;

class CXmppSettingsColumn;

/**

 *  This class handles dynamic name-value pair storing.

 *  Be warned, all actions are final.

 *

 *

 *  This is how this component works:

 *  It has two tables. First one, the column table, contains only single row.

 *  This table is actually a header table for the record table. When you set

 *  an new attribute, we check that does it already exist in column table. If

 *  it does not, it is added as last entry. After that data of the attribute 

 *  is set to the record table into same column as it is attribute name is in

 *  the column table. Row of the settings record is determined by

 *  given settingsrecordid.

 *

 *  The column table can hold 0xFFFE (65534) of different user attributes

 *  and you can add 0xFF (255) different settingsrecords.

 *

 *  Below is an picture of the tables. Only the ID column is mandatory. All 

 *  other columns are defined by user.

 *

 *   ------------------------------------------------------------

 *   | COLUMNS TABLE                                             |

 *   |-----------------------------------------------------------

 *   | 1  |     2       |      3      |    4     |  5... |      |

 *   ------------------------------------------------------------

 *   | ID | SERVER-ADDR | SERVER-PORT | USERNAME | etc...|      |

 *   ------------------------------------------------------------

 *   

 *   ------------------------------------------------------------

 *   | RECORDS TABLE                                            |

 *   |-----------------------------------------------------------

 *   |  1 |          2          |  3   |    4    |  5... |      |

 *   ------------------------------------------------------------

 *   |  1 |   www.gizmo.com     | 5223 | Myerdin | etc...|      |

 *   ------------------------------------------------------------

 *   |  2 |                     | 5222 | Ballmer | etc...|      |

 *   ------------------------------------------------------------

 *   |  3 |   login.com         |      | Apple   | etc...|      |

 *   ------------------------------------------------------------

 *   |  4 |   aaa.bbb.com       | 1234 | user    | etc...|      |

 *   ------------------------------------------------------------

 * 

 *  Usage examples: 

 *  @code

 *  ---- Example 1 ----------------------------------------------

 *   Usage example:

 *   First Create settings record:

 *

 *   TUint32 settingId(0);

 *   CXmppSettingsApi* sapi = CXmppSettingsApi::NewLC();

 *   sapi->CreateSettingsRecordL( settingId );

 *   CleanupStack::PopAndDestroy( sapi );

 *

 *   The settingId contains now new id.

 *

 * ---- Example 2 ----------------------------------------------

 *   You can request default settings record (currently returns the first):

 *

 *   TUint32 settingId(0);

 *   sapi->DefaultSettingsRecordL( settingId );

 *

 *   The settingId contains now the id.

 *

 *  ---- Example 3 ----------------------------------------------

 *   When you want to add new parameter to the settings record, do following:

 *

 *   _LIT( KOurParam, "USERNAME");

 *

 *   sapi->SetParamL( settingId,

 *                    KOurParam(),

 *                    aUsername );

 *

 *   If this is the first time the parameter is added to the settings record,

 *   it creates new room for it.

 *

 *  ---- Example 4 ----------------------------------------------

 *   When you want to get parameter from the settings record, do following:

 *

 *   _LIT( KOurParam, "USERNAME");

 *   RBuf value;

 *   value.CreateL( KMaxParamLength );

 *

 *   sapi->SetParamL( settingId,

 *                    KOurParam(),

 *                    value );

 *

 *   Value now contains the value recordd in the settings record. If no value

 *   has been set for this settins records column, then it cannot be

 *   found ->leaves KErrNotFound.

 *

 *  @endcode

 *

 *  @lib jabbersettings.lib

 *  @since S60 5.0

 */

class CXmppSettingsApi: public CBase

    {

public:

		/**

     * Two-phased constructor.         

     * @return Instance of this class

     */

    IMPORT_C static CXmppSettingsApi* NewL();

    IMPORT_C static CXmppSettingsApi* NewLC();

		/**

	   * Destructor

	   */

    IMPORT_C virtual ~CXmppSettingsApi();

    /**

     * Creates new settings record.

     *

     * @since S60 5.0

     * @param aSettingsRecordId On return contains the new setting id.

     */

    IMPORT_C void CreateSettingsRecordL( TUint32& aSettingsRecordId );

    /**

     * Removes Settings record using given settings record id.

     *

     * @since S60 5.0

     * @param aSettingsRecordId Setting id to be removed.

     */

    IMPORT_C void RemoveSettingsRecordL( TUint32 aSettingsRecordId );

    /**

     * Returns default settings record id.

     *

     * @since S60 5.0

     * @param aSettingsRecordId On return contains the setting id.

     */

    IMPORT_C void DefaultSettingsRecordL( TUint32& aSettingsRecordId );

    /**

     * Fills the array with settings ids. If there is none, array

     * is zero length.

     *

     * @since S60 5.0

     * @param aArray Array is filled with setting ids.

     */

    IMPORT_C void GetSettingsRecordIdArrayL( RArray<TUint32>& aArray );

    /**

     * Sets value of the param. If ParamName is not found, it creates new.

     *

     * @since S60 5.0

     * @param aSettingsRecordId Setting id of interest.

     * @param aAttrName Parameters name.

     * @param aAttrValue Parameters value.

     */

    IMPORT_C void SetParamL( TUint32 aSettingsRecordId,

                             const TDesC& aAttrName,

                             const TDesC& aAttrValue );

    /**

     * Sets value of the param. If ParamName is not found, it creates new.

     *

     * @since S60 5.0

     * @param aSettingsRecordId Setting id of interest.

     * @param aAttrName Parameters name.

     * @param aAttrValue Parameters value.

     */

    IMPORT_C void SetParamL( TUint32 aSettingsRecordId,

                             const TDesC& aAttrName,

                             TInt aAttrValue );

    /**

     * Gets value of the param.

     * - KErrNotFound if setting collection or Param is not found.

     *

     * @since S60 5.0

     * @param aSettingsRecordId Setting id of interest.

     * @param aAttrName Parameters name.

     * @param aAttrValue On return, contains the param value.

     */

    IMPORT_C void GetParamL( TUint32 aSettingsRecordId,

                             const TDesC& aAttrName,

                             TDes& aAttrValue );

    /**

     * Gets value of the param.

     * - KErrNotFound if setting collection or Param is not found.

     *

     * @since S60 5.0

     * @param aSettingsRecordId Setting id of interest.

     * @param aAttrName Parameters name.

     * @param aAttrValue On return, contains the param value.

     */

    IMPORT_C void GetParamL( TUint32 aSettingsRecordId,

                                const TDesC& aAttrName,

                                TInt& aAttrValue );

    /**

     * Removes this param from this Settings record.

     * - KErrNotFound If Settings record or param is not found.

     *

     * @since S60 5.0

     * @param aSettingsRecordId Setting id.

     * @param aAttrName Parameters name.

     */

    IMPORT_C void RemoveParamL( TUint32 aSettingsRecordId,

                                const TDesC& aAttrName );

	 /**

     * This method does checks before setting or getting values.

     *

     * @since S60 5.0

     * @param aSettingsRecordId Setting id to be changed.

     * @param aAttrName Parameters name.

     * @param aCreateColumnIfNotExist Should new column be created if it is not

     *                         founded (by aAttrName).

     * @param aTheKey On return contains key to be created/changed.

     */

    IMPORT_C void GetRepositoryKeyL( TUint32 aSettingsRecordId,

                       const TDesC& aAttrName,

                       TBool aCreateColumnIfNotExist,

                       TUint32& aTheKey );

private:

		/**

		 * Default Contructor

		 */

    CXmppSettingsApi();

    void ConstructL();

   	 /**

     * This method does checks before setting or getting values.

     *

     * @since S60 5.0

     * @param aSettingsRecordId Setting id to be changed.

     * @param aAttrName Parameters name.

     * @param aCreateColumnIfNotExist Should new column be created if it is not

     *                         founded (by aAttrName).

     * @param aTheKey On return contains key to be created/changed.

     */

    void GetColumnKeyL( TUint32 aSettingsRecordId,

                       const TDesC& aAttrName,

                       TBool aCreateColumnIfNotExist,

                       TUint32& aTheKey );

private: // data

    /**

     * Central Repository.

     * Own.

     */

    CRepository* iRepository;

    /**

     * Class for settings records handling.

     * Own.

     */

    CXmppSettingsRecord* iRecords;

    /**

     * Class for column table handling.

     * Own.

     */

    CXmppSettingsColumn* iColumns;

    };

#endif // C_XMPPSETTINGSAPI_H