--- /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 <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