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:  XML Parser implementation

    15 *

    16 */

    17 

    18 #ifndef MPENGPARSER_H

    19 #define MPENGPARSER_H

    20 

    21 #include "PEngXMLTags.h"

    22 //#include "MPEngAdvTransactionStatus2.h"

    23 

    24 

    25 

    26 //FORWARD DECLARATION

    27 class MPEngXMLParser;

    28 class MPEngAdvTransactionStatus2;

    29 

    30 

    31 

    32 // FUNCTION PROTOTYPES

    33 

    34 /**

    35  * Factory method to create XML Parser.

    36  *

    37  * @since 3.0

    38  */

    39 IMPORT_C MPEngXMLParser* CreateXMLParserL();

    40 IMPORT_C MPEngXMLParser* CreateXMLParserLC();

    41 

    42 

    43 

    44 

    45 

    46 //  CLASS DEFINITION

    47 /**

    48  * This class defines the interface for Presence XML Parser.

    49  * XML parser is used to parse XML data.

    50  *

    51  * @since 2.1

    52  */

    53 class MPEngXMLParser

    54     {

    55     public: //Parsing functions

    56 

    57 

    58         /**

    59          * Decodes given XML data according to the given string to be found.

    60          * @param aBuffer Initial data to be parsed

    61          * @param aString The tag name to be searched

    62          * @param aTags Tells if the tags are included in the result

    63          * @param aLevel Restricts the parsing to a certain tag level, 0 means

    64          *                that there's no restrictions

    65          * @return TBool The boolean value of how decoding went.

    66          */

    67         virtual TBool DecodeL( const TDesC8& aBuffer,

    68                                const TDesC8& aString,

    69                                TBool aTags,

    70                                TInt aLevel = 0 ) = 0;

    71 

    72 

    73         /**

    74          * Gets the number of decode results.

    75          * @return TInt number of results.

    76          */

    77         virtual TInt Count() = 0;

    78 

    79 

    80 

    81         /**

    82          * Gets raw result from the decoded result array.

    83          *

    84          * @param aIndex the wanted result

    85          * @return TPtrC8 a pointer to the result data

    86          */

    87         virtual TPtrC8 ResultL( TInt aIndex = 0 ) = 0;

    88 

    89 

    90 

    91         /**

    92          * Gets narrow text from the decoded result array.

    93          *

    94          * Performed steps:

    95          * 1. UnEscapes XML entities.

    96          *

    97          * @param aIndex Index of wanted result.

    98          * @return Narrow text. Buffer ownership is returned to caller.

    99          */

   100         virtual HBufC8* ResultAsNarrowTextL( TInt aIndex = 0 ) = 0;

   101 

   102 

   103 

   104         /**

   105          * Gets unicode text from the decoded result array.

   106          *

   107          * Performed steps:

   108          * 1. UnEscapes XML entities.

   109          * 2. Converts text from Utf8 to Unicode.

   110          *

   111          * @param aIndex Index of wanted result.

   112          * @return Unicode text. Buffer ownership is returned to caller.

   113          */

   114         virtual HBufC16* ResultAsUnicodeTextL( TInt aIndex = 0 ) = 0;

   115 

   116 

   117 

   118         /**

   119          * Gets WV Address from the decoded result array.

   120          *

   121          * Performed steps:

   122          * 1. UnEscapes XML entities.

   123          * 2. Converts text from Utf8 to Unicode.

   124          * 3. UnEscapes WV Address characters

   125          *

   126          * @param aIndex Index of wanted result.

   127          * @return WV Address. Buffer ownership is returned to caller.

   128          */

   129         virtual HBufC16* ResultAsWVAddressL( TInt aIndex = 0 ) = 0;

   130 

   131 

   132 

   133         /**

   134          * Gets Base64Decodeddata from the decoded result array.

   135          *

   136          * Performed steps:

   137          * 1. Coverts data from the BASE64 format

   138          *

   139          * @param aIndex Index of wanted result.

   140          * @return Base64 decoded text. Buffer ownership is returned to caller.

   141          */

   142         virtual HBufC8* ResultAsBase64DecodedL( TInt aIndex = 0 ) = 0;

   143 

   144 

   145 

   146 

   147     public: //Transaction result parsing functions

   148 

   149 

   150         /**

   151          * Parses the transaction result from the XML data.

   152          * Overloaded version to allow client to define

   153          * wether the valid result structure is required or not.

   154          *

   155          * @param aBuffer The XML buffer containing the response

   156          * @param aTransactionOperation The TransactionOperation that

   157          * caused the possible detailed errors.

   158          * @param aStatus MPEngAdvTransactionStatus object where the

   159          * userIDs and return values are stored.

   160          * @param aResultRequired If ETrue, the valid result

   161          * structure is required. If EFalse, or valid result

   162          * structure is not required. If valid result

   163          * structure is required but it isnt found from XML,

   164          * parser generates KPEngNwErrInternalServerOrNetworkError.

   165          * On the return aResultRequired contains ETrue, if valid

   166          * structure was found. Else EFalse.

   167          * @return The main result value from transaction status.

   168          */

   169         virtual TInt ParseResultL( const TDesC8& aBuffer,

   170                                    TInt aTransactionOperation,

   171                                    MPEngAdvTransactionStatus2& aStatus,

   172                                    TBool& aResultRequired ) = 0;

   173 

   174         /**

   175          * Parses the transaction result from the XML data.

   176          * Overloaded version requiring the valid result

   177          * structure.

   178          *

   179          * @param aBuffer The XML buffer containing the response

   180          * @param aTransactionOperation The TransactionOperation that

   181          * caused the possible detailed errors.

   182          * @param aStatus MPEngAdvTransactionStatus object where the

   183          * userIDs and return values are stored.

   184          * @return The main result value from transaction status.

   185          */

   186         virtual TInt ParseResultL( const TDesC8& aBuffer,

   187                                    TInt aTransactionOperation,

   188                                    MPEngAdvTransactionStatus2& aStatus ) = 0;

   189 

   190         /**

   191          * Parses the transaction result from the XML data.

   192          * Client can pass the contact list id, where the results relate.

   193          * Requires the valid result structure.

   194          *

   195          * @param aBuffer The XML buffer containing the response

   196          * @param aTransactionOperation The TransactionOperation that

   197          * caused the possible detailed errors.

   198          * @param aStatus MPEngAdvTransactionStatus object where the

   199          * userIDs and return values are stored.

   200          * @param aContactList The name of the contact list this result was

   201          * attached to.

   202          * @return The main result value from transaction status.

   203          */

   204         virtual TInt ParseContactListResultL( const TDesC8& aBuffer,

   205                                               TInt aTransactionOperation,

   206                                               const TDesC& aContactList,

   207                                               MPEngAdvTransactionStatus2& aStatus ) = 0;

   208 

   209 

   210 

   211 

   212     public: //Destructor & Cleanup support

   213 

   214         /**

   215          *  Release method.

   216          *  When called, deletes object and

   217          *  frees all its resources.

   218          *

   219          *  Concrete parser object can be thus pushed

   220          *  on the CleanupStack using CleanupClosePushL().

   221          */

   222         virtual void Close() = 0;

   223 

   224 

   225         /**

   226          * Inline virtual destructor.

   227          * Concrete instancies can be deleted

   228          * trough this interface.

   229          */

   230         virtual ~MPEngXMLParser() {}

   231 

   232 

   233     };

   234 

   235 #endif      //  MPENGPARSER_H

   236 

   237 //  End of File