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

    15 *

    16 */

    17 

    18 

    19 #ifndef C_XMPPSETTINGSAPI_H

    20 #define C_XMPPSETTINGSAPI_H

    21 

    22 

    23 

    24 #include <e32base.h>

    25 

    26 class CRepository;

    27 class CXmppSettingsRecord;

    28 class CXmppSettingsColumn;

    29 

    30 

    31 /**

    32  *  This class handles dynamic name-value pair storing.

    33  *  Be warned, all actions are final.

    34  *

    35  *

    36  *  This is how this component works:

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

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

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

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

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

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

    43  *  given settingsrecordid.

    44  *

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

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

    47  *

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

    49  *  other columns are defined by user.

    50  *

    51  *   ------------------------------------------------------------

    52  *   | COLUMNS TABLE                                             |

    53  *   |-----------------------------------------------------------

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

    55  *   ------------------------------------------------------------

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

    57  *   ------------------------------------------------------------

    58  *   

    59  *   ------------------------------------------------------------

    60  *   | RECORDS TABLE                                            |

    61  *   |-----------------------------------------------------------

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

    63  *   ------------------------------------------------------------

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

    65  *   ------------------------------------------------------------

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

    67  *   ------------------------------------------------------------

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

    69  *   ------------------------------------------------------------

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

    71  *   ------------------------------------------------------------

    72  * 

    73  *  Usage examples: 

    74  *  @code

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

    76  *   Usage example:

    77  *   First Create settings record:

    78  *

    79  *   TUint32 settingId(0);

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

    81  *   sapi->CreateSettingsRecordL( settingId );

    82  *   CleanupStack::PopAndDestroy( sapi );

    83  *

    84  *   The settingId contains now new id.

    85  *

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

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

    88  *

    89  *   TUint32 settingId(0);

    90  *   sapi->DefaultSettingsRecordL( settingId );

    91  *

    92  *   The settingId contains now the id.

    93  *

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

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

    96  *

    97  *   _LIT( KOurParam, "USERNAME");

    98  *

    99  *   sapi->SetParamL( settingId,

   100  *                    KOurParam(),

   101  *                    aUsername );

   102  *

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

   104  *   it creates new room for it.

   105  *

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

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

   108  *

   109  *   _LIT( KOurParam, "USERNAME");

   110  *   RBuf value;

   111  *   value.CreateL( KMaxParamLength );

   112  *

   113  *   sapi->SetParamL( settingId,

   114  *                    KOurParam(),

   115  *                    value );

   116  *

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

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

   119  *   found ->leaves KErrNotFound.

   120  *

   121  *  @endcode

   122  *

   123  *  @lib jabbersettings.lib

   124  *  @since S60 5.0

   125  */

   126 class CXmppSettingsApi: public CBase

   127     {

   128 

   129 public:

   130 		

   131 		/**

   132      * Two-phased constructor.         

   133      * @return Instance of this class

   134      */

   135     IMPORT_C static CXmppSettingsApi* NewL();

   136 

   137     IMPORT_C static CXmppSettingsApi* NewLC();

   138 		

   139 		/**

   140 	   * Destructor

   141 	   */

   142     IMPORT_C virtual ~CXmppSettingsApi();

   143 

   144 

   145     /**

   146      * Creates new settings record.

   147      *

   148      * @since S60 5.0

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

   150      */

   151     IMPORT_C void CreateSettingsRecordL( TUint32& aSettingsRecordId );

   152 

   153     /**

   154      * Removes Settings record using given settings record id.

   155      *

   156      * @since S60 5.0

   157      * @param aSettingsRecordId Setting id to be removed.

   158      */

   159     IMPORT_C void RemoveSettingsRecordL( TUint32 aSettingsRecordId );

   160 

   161     /**

   162      * Returns default settings record id.

   163      *

   164      * @since S60 5.0

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

   166      */

   167     IMPORT_C void DefaultSettingsRecordL( TUint32& aSettingsRecordId );

   168 

   169     /**

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

   171      * is zero length.

   172      *

   173      * @since S60 5.0

   174      * @param aArray Array is filled with setting ids.

   175      */

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

   177 

   178     /**

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

   180      *

   181      * @since S60 5.0

   182      * @param aSettingsRecordId Setting id of interest.

   183      * @param aAttrName Parameters name.

   184      * @param aAttrValue Parameters value.

   185      */

   186     IMPORT_C void SetParamL( TUint32 aSettingsRecordId,

   187                              const TDesC& aAttrName,

   188                              const TDesC& aAttrValue );

   189 

   190     /**

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

   192      *

   193      * @since S60 5.0

   194      * @param aSettingsRecordId Setting id of interest.

   195      * @param aAttrName Parameters name.

   196      * @param aAttrValue Parameters value.

   197      */

   198     IMPORT_C void SetParamL( TUint32 aSettingsRecordId,

   199                              const TDesC& aAttrName,

   200                              TInt aAttrValue );

   201 

   202     /**

   203      * Gets value of the param.

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

   205      *

   206      * @since S60 5.0

   207      * @param aSettingsRecordId Setting id of interest.

   208      * @param aAttrName Parameters name.

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

   210      */

   211     IMPORT_C void GetParamL( TUint32 aSettingsRecordId,

   212                              const TDesC& aAttrName,

   213                              TDes& aAttrValue );

   214 

   215     /**

   216      * Gets value of the param.

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

   218      *

   219      * @since S60 5.0

   220      * @param aSettingsRecordId Setting id of interest.

   221      * @param aAttrName Parameters name.

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

   223      */

   224     IMPORT_C void GetParamL( TUint32 aSettingsRecordId,

   225                                 const TDesC& aAttrName,

   226                                 TInt& aAttrValue );

   227 

   228     /**

   229      * Removes this param from this Settings record.

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

   231      *

   232      * @since S60 5.0

   233      * @param aSettingsRecordId Setting id.

   234      * @param aAttrName Parameters name.

   235      */

   236     IMPORT_C void RemoveParamL( TUint32 aSettingsRecordId,

   237                                 const TDesC& aAttrName );

   238 

   239 	

   240 	 /**

   241      * This method does checks before setting or getting values.

   242      *

   243      * @since S60 5.0

   244      * @param aSettingsRecordId Setting id to be changed.

   245      * @param aAttrName Parameters name.

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

   247      *                         founded (by aAttrName).

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

   249      */

   250     IMPORT_C void GetRepositoryKeyL( TUint32 aSettingsRecordId,

   251                        const TDesC& aAttrName,

   252                        TBool aCreateColumnIfNotExist,

   253                        TUint32& aTheKey );

   254                        

   255 private:

   256 		

   257 		/**

   258 		 * Default Contructor

   259 		 */

   260     CXmppSettingsApi();

   261 

   262     void ConstructL();

   263 

   264    	 /**

   265      * This method does checks before setting or getting values.

   266      *

   267      * @since S60 5.0

   268      * @param aSettingsRecordId Setting id to be changed.

   269      * @param aAttrName Parameters name.

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

   271      *                         founded (by aAttrName).

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

   273      */

   274     void GetColumnKeyL( TUint32 aSettingsRecordId,

   275                        const TDesC& aAttrName,

   276                        TBool aCreateColumnIfNotExist,

   277                        TUint32& aTheKey );

   278 

   279 private: // data

   280 

   281     /**

   282      * Central Repository.

   283      * Own.

   284      */

   285     CRepository* iRepository;

   286 

   287     /**

   288      * Class for settings records handling.

   289      * Own.

   290      */

   291     CXmppSettingsRecord* iRecords;

   292 

   293     /**

   294      * Class for column table handling.

   295      * Own.

   296      */

   297     CXmppSettingsColumn* iColumns;

   298 

   299     };

   300 

   301 #endif // C_XMPPSETTINGSAPI_H