diff -r 000000000000 -r 61fad867f68e imsrv_plat/xmpp_settings_api/inc/xmppservicesettingsapi.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/imsrv_plat/xmpp_settings_api/inc/xmppservicesettingsapi.h Wed Nov 03 09:32:20 2010 +0530 @@ -0,0 +1,301 @@ +/* +* 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 + +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& 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