1 /*

     2 * Copyright (c) 2004 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:  Key - value container.

    15 *

    16 */

    17 

    18 #ifndef __CIMPSSAPKEYVALUEPAIR_H

    19 #define __CIMPSSAPKEYVALUEPAIR_H

    20 

    21 //  INCLUDES

    22 #include <e32base.h>

    23 #include <s32strm.h>

    24 

    25 // CLASS DECLARATION

    26 /**

    27  * Key - value container.

    28  * Can be derived to expand services.

    29  *

    30  * @since 3.0

    31  **/

    32 NONSHARABLE_CLASS( CIMPSSAPKeyValuePair ): public CBase

    33     {

    34 public:  // Enumerations

    35 

    36     /**

    37      * Data type enumeration.

    38      * List supported value data types.

    39      * @since 3.0

    40      **/

    41     enum TValueType

    42         {

    43         EValueTypeNone = 0,

    44         EValueTypeInt,

    45         EValueTypeDesC8,

    46         EValueTypeDesC16

    47         };

    48 

    49 

    50 public:  // Constructors and destructor

    51 

    52     /**

    53      * Non leaving two phased constructor.

    54      *

    55      * If object allocation fails, returns NULL.

    56      *

    57      * @since 3.0

    58      * @param aKey The key.

    59      */

    60     static CIMPSSAPKeyValuePair* New( const TDesC& aKey );

    61 

    62     /**

    63      * Two phased constructor initializing object state

    64      * from the stream.

    65      *

    66      * @since 3.0

    67      * @param aStream The stream to read object state.

    68      */

    69     static CIMPSSAPKeyValuePair* NewLC( RReadStream& aStream );

    70 

    71     /**

    72      * Two phased constructor initializing object state

    73      * from given flat descriptor.

    74      *

    75      * @since 3.0

    76      * @param aKeyValuePairFlat The flat representation of key-value pair

    77      */

    78 

    79     static CIMPSSAPKeyValuePair* NewLC( const TDesC& aKeyValuePairFlat );

    80 

    81     /**

    82      * Destructor.

    83      */

    84     virtual ~CIMPSSAPKeyValuePair();

    85 

    86 

    87 

    88 protected:  // Constructor

    89 

    90     /**

    91      * C++ default constructor.

    92      */

    93     CIMPSSAPKeyValuePair();

    94 

    95 

    96     /**

    97      * Symbian OS constructor.

    98      * Initializes object state from given stream.

    99      *

   100      * @since 3.0

   101      * @param aStream The stream to read object state.

   102      */

   103     void ConstructL( RReadStream& aStream );

   104 

   105 

   106 public:  //Data access

   107 

   108     /**

   109      * Key accessor.

   110      *

   111      * Gets the key associated with key-value object.

   112      * Virtual to allow derived classes to expand behaviour.

   113      *

   114      * @since 3.0

   115      * @return The key.

   116      */

   117     virtual const TDesC& Key() const;

   118 

   119 

   120     /**

   121      * Data setters.

   122      *

   123      * Overloaded to support integer type and

   124      * narrow and wide descriptors.

   125      *

   126      * @since 3.0

   127      * @param aValue The value to assign for key-value object.

   128      * @return Error code. One of following:

   129      * KErrNone: Value assigned/updated succesfully.

   130      * KErrGeneral: Different data type already assigned.

   131      * KErrNoMemory: No memory to allocate the new value.

   132      * Original value remains if assigning new value fails.

   133      */

   134     TInt SetValue( TInt aValue );

   135     TInt SetValue( const TDesC8& aValue );

   136     TInt SetValue( const TDesC16& aValue );

   137 

   138 

   139     /**

   140      * Data getters.

   141      *

   142      * Overloaded to support integer type and

   143      * narrow and wide descriptors.

   144      *

   145      * @since 3.0

   146      * @param aValue The value to get.

   147      * @return Error code. One of following:

   148      * KErrNone: Value read succesfully.

   149      * KErrNotFound: No value yet assigned.

   150      * KErrGeneral: Different data type assigned.

   151      * Given aValue isn't changed if reading fails.

   152      */

   153     TInt GetValue( TInt& aValue ) const;

   154     TInt GetValue( TPtrC8& aValue ) const;

   155     TInt GetValue( TPtrC16& aValue ) const;

   156 

   157 

   158     /**

   159      * Key-Value pair flat representation

   160      *

   161      * Creates flat representation of the key-value pair

   162      * and pushes it in cleanup stack.

   163      * Ownership is transferred to calling method.

   164      *

   165      * @since 3.0

   166      * @return The flat representation of key-value pair

   167      */

   168 

   169     HBufC* KeyValuePairFlatLC();

   170 

   171 

   172 public:  // Streaming support

   173 

   174 

   175     /**

   176      * Externalises the value pair to given stream.

   177      *

   178      * @since 3.0

   179      * @param aStream stream to write to.

   180      */

   181     void ExternalizeL( RWriteStream& aStream ) const;

   182 

   183 

   184     /**

   185      * Approximates the value pair data size.

   186      *

   187      * @since 3.0

   188      * @return The value pair data size.

   189      */

   190     TInt DataSize() const;

   191 

   192     /**

   193      * Approximates the value pair data size

   194      * in decimal textual representation

   195      *

   196      * @since 3.0

   197      * @return The value pair data size.

   198      */

   199     TInt DataSizeDec() const;

   200 

   201     /**

   202     * Checks if the data fits in the flat

   203     * descriptor

   204     *

   205     * @since 3.0

   206     * @return ETrue if data is too big.

   207     */

   208 

   209     TBool IsDataTooBig() const;

   210 

   211 private:    // Help functions

   212 

   213     /**

   214      * Resets the value pair data.

   215      * @since 3.0

   216      */

   217     void Reset();

   218 

   219     /**

   220      * Parses value pair data from flat descriptor.

   221      * @param aKeyValuePairFlat flat descriptor to parse

   222      * @since 3.0

   223      */

   224     void ParseFlatKeyValuePairL( const TDesC& aKeyValuePairFlat );

   225 

   226 private:    // Data

   227 

   228 

   229     HBufC16*        iKey;           //OWN: The key.

   230 

   231     TValueType      iValueType;     //OWN: The value type.

   232 

   233     union                           //OWN: The value. Value type is determined from iValueType.

   234         {

   235         TInt        iInt;

   236         HBufC8*     iBuf8;

   237         HBufC16*    iBuf16;

   238         };

   239 

   240     };

   241 

   242 #endif      // __CIMPSSAPKEYVALUEPAIR_H

   243 

   244 

   245 //  End of File

   246