1 /*

     2 * Copyright (c) 2005 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:   XDM Engine

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #ifndef __XDMENGINE__

    22 #define __XDMENGINE__

    23 

    24 // INCLUDES

    25 #include "e32base.h"

    26 #include "XdmDocument.h"

    27 #include "XdmDirectory.h"

    28 

    29 enum TXdmEnginePanic

    30     {

    31     EDocNodeNull = 0,

    32     ENodeNotEmpty,

    33     EDDocModelNotFound,

    34     EDirModelNotFound,

    35     EIllegalPosition,

    36     EIndexOutOfBounds,

    37     };

    38     

    39 //CONSTANTS

    40 _LIT( KXdmEngLogFile,                                  "XdmEngine" );

    41 _LIT8( KGeneralEqualsAndQuotes,                        "=\""  );

    42 _LIT8( KGeneralQuotes,                                 "\""  );

    43 _LIT8( KGeneralSpace,                                  " ");

    44 const TInt KXdmEngLogBufferMaxSize		               = 2000;

    45 const TInt KXdmEngShutdownDelay		                   = 10;

    46 

    47 //FORWARD DECLARATIONS

    48 class CDesC16Array;

    49 class CXdmProtocol;

    50 class CXdmDocument;

    51 class CXdmDirectory;

    52 class CXdmLogWriter;

    53 class CXdmProtocolInfo;

    54 

    55 // CLASS DECLARATION

    56 class CXdmEngine : public CActive

    57     {

    58     public:  // Constructors and destructor

    59 

    60         /**

    61         * Create an instance of the Engine object

    62         * @param CXdmProtocolInfo& Reference to a protocol info object

    63         * @return CXdmEngine*

    64         */     

    65         IMPORT_C static CXdmEngine* NewL( const CXdmProtocolInfo& aProtocolInfo );

    66         

    67         /**

    68         * Fetch the IDs of the XDM Settings which have been

    69         * configured to this device.

    70         *

    71         * @param RArray<TInt> On return, contains the TInt type IDs

    72         *                     which correspond to the names stored

    73         *                     in the returning array object.

    74         * @return CDesC16Array* The names of the settings

    75         */

    76         IMPORT_C static CDesC16Array* XdmSettingsLC( RArray<TInt>& aSettingIds );

    77         

    78         /**

    79         * Create a new document model

    80         *

    81         * @param TDesC8& Name of the document, including path

    82         * @param TDesC8& Application usage - an AUID

    83         *

    84         * NOTE! It is important to keep in mind that the Xdm Engine

    85         *       DOES NOT maintain the documents created on this engine

    86         *       object. It is the responsibility of the client application

    87         *       to deallocate the documents it creates by calling

    88         *       CXdmEngine::DeleteDocumentModelL( model ). The engine

    89         *       does keep track of the documents that are constructed

    90         *       on it, but it does not own them in the sense which would

    91         *       suggest deallocation of the memory reserved for them.

    92         *

    93         * @return CXdmDocument instance

    94         */     

    95         IMPORT_C CXdmDocument* CreateDocumentModelL( const TDesC& aDocumentName,

    96                                                      const TXdmDocType aDocumentType );

    97 

    98         /**

    99         * Create a new document model

   100         *

   101         * @param CXdmDocument* The document model to delete

   102         * @return void 

   103         */     

   104         IMPORT_C void DeleteDocumentModelL( const CXdmDocument* aDocument );

   105         

   106         /**

   107         * Create a new document model

   108         *

   109         * @param CXdmDocument* The document model to delete

   110         * @return void 

   111         */     

   112         IMPORT_C CXdmDirectory* CreateDirectoryModelL( const TDesC& aDirectoryPath );

   113         

   114         /**

   115         * Create a new document model

   116         *

   117         * @param CXdmDocument* The document model to delete

   118         * @return void 

   119         */     

   120         IMPORT_C void DeleteDirectoryModelL( const CXdmDirectory* aDocument );

   121         

   122         /**

   123         * Create a new element.

   124         *

   125         * The returning CXdmDocumentNode object does not yet 

   126         * belong to any document. Therefore it is the responsibility

   127         * of the client application to deallocate the memory

   128         * reserved for the element.

   129         *

   130         * The new element can be "attached" to a document by using

   131         * AppendToModelL() or ReplaceInModelL(). It is important to

   132         * note that even after calling either of these methods, the

   133         * ownership of the object does not change.

   134         *

   135 		* @return CXdmDocumentNode* 

   136         */

   137         IMPORT_C CXdmDocumentNode* CreateDocumentNodeL();

   138         

   139         /**

   140         * Update the changes to the specified document model

   141         *

   142         * @param The document to be updated

   143         * @param TRequestStatus Request status of the caller

   144         * @return void

   145         */     

   146         IMPORT_C void UpdateL( CXdmDocument* aDocument,

   147                                TRequestStatus& aStatus );

   148         

   149         /**

   150         * Update the contents of the specified directory model

   151         *

   152         * @param The directory to be updated

   153         * @param TRequestStatus Request status of the caller

   154         * @return void

   155         */     

   156         IMPORT_C void UpdateL( TRequestStatus& aStatus,

   157                                CXdmDirectory* aDirectory,

   158                                TDirUpdatePhase aUpdatePhase );

   159 

   160 

   161         /**

   162         * Cancel an update operation on a document

   163         *

   164         * @param CXdmDocument The document whose update

   165         *                     is being cancelled

   166         * @return void

   167         */     

   168         IMPORT_C void CancelUpdate( CXdmDocument* aDocument );

   169         

   170         /**

   171         * Cancel an update operation on a directory

   172         *

   173         * @param CXdmDirectory The directory whose update

   174         *                      is being cancelled

   175         * @return void

   176         */     

   177         IMPORT_C void CancelUpdate( CXdmDirectory* aDirectory );

   178         

   179         /**

   180         * Get the list of documents created on this instance

   181         *

   182         * @return RPointerArray The list of document models

   183         */     

   184         IMPORT_C const RPointerArray<CXdmDocument>& DocumentCollection() const;

   185         

   186         /**

   187         * Get the list of directories created on this instance

   188         *

   189         * @return RPointerArray The list of document models

   190         */     

   191         IMPORT_C const RPointerArray<CXdmDirectory>& DirectoryCollection() const;

   192         

   193         /**

   194         * Destructor.

   195         */      

   196         IMPORT_C virtual ~CXdmEngine();

   197 

   198     public:   //New functions 

   199         

   200         /**

   201         * Return the protocol this engine uses

   202         *

   203         * @return CXdmProtocol* The protocol instance

   204         */ 

   205         CXdmProtocol* XdmProtocol() const;

   206 

   207         /**

   208         * Logging function

   209         *

   210         * @param TRefByValue<const TDesC8> aFmt,...

   211         * @return void

   212         */ 

   213         void WriteToLog( TRefByValue<const TDesC8> aFmt,... ) const;

   214     

   215     public:  //Static

   216      

   217         /**

   218         * Convert data from UNICODE to UTF-8

   219         *

   220         * @param TDesC& UNICODE descriptor

   221         * @return HBufC8* Data converted to UTF-8

   222         */ 

   223         static HBufC8* ConvertToUTF8L( const TDesC& aUnicodeDesc );

   224 

   225     private:

   226         

   227         /**

   228         * C++ default constructor is private

   229         * @return void

   230         */      

   231         CXdmEngine();

   232         

   233         /**

   234         * Symbian OS second-phase constructor

   235         * @param CXdmProtocolInfo& Protocol information

   236         * @return void

   237         */ 

   238         void ConstructL( CXdmProtocolInfo& aProtocolInfo );

   239 

   240         /**

   241         * From CActive.

   242         * @return void

   243         */

   244 		void RunL();

   245 

   246         /**

   247         * From CActive.

   248         * @return void

   249         */

   250 		void DoCancel();

   251         

   252     private: //Data

   253 

   254         enum TXdmEngineState

   255             {

   256             EXdmEngineIdle = 0,

   257             EXdmEngineStartDocUpdate,

   258             EXdmEngineStartDirUpdate

   259             };

   260         

   261         CXdmProtocol*                           iXdmProtocol;

   262         CXdmDocument*                           iCurrentDoc;

   263         CXdmDirectory*                          iCurrentDir;

   264         TRequestStatus*                         iClientStatus;

   265         RPointerArray<CXdmDocument>             iDocumentQueue;

   266         RPointerArray<CXdmDocument>             iDocUpdateQueue;

   267         RPointerArray<CXdmDirectory>            iDirUpdateQueue;

   268         RPointerArray<CXdmDirectory>            iDirectoryQueue;

   269         CXdmLogWriter*                          iLogWriter;

   270     };

   271 

   272 #endif

   273 

   274 

   275 // End of File