/*
* Copyright (c) 2005 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: XDM Engine
*
*/
#ifndef __XDMENGINE__
#define __XDMENGINE__
// INCLUDES
#include "e32base.h"
#include "XdmDocument.h"
#include "XdmDirectory.h"
enum TXdmEnginePanic
{
EDocNodeNull = 0,
ENodeNotEmpty,
EDDocModelNotFound,
EDirModelNotFound,
EIllegalPosition,
EIndexOutOfBounds,
};
//CONSTANTS
_LIT( KXdmEngLogFile, "XdmEngine" );
_LIT8( KGeneralEqualsAndQuotes, "=\"" );
_LIT8( KGeneralQuotes, "\"" );
_LIT8( KGeneralSpace, " ");
const TInt KXdmEngLogBufferMaxSize = 2000;
const TInt KXdmEngShutdownDelay = 10;
//FORWARD DECLARATIONS
class CDesC16Array;
class CXdmProtocol;
class CXdmDocument;
class CXdmDirectory;
class CXdmLogWriter;
class CXdmProtocolInfo;
// CLASS DECLARATION
class CXdmEngine : public CActive
{
public: // Constructors and destructor
/**
* Create an instance of the Engine object
* @param CXdmProtocolInfo& Reference to a protocol info object
* @return CXdmEngine*
*/
IMPORT_C static CXdmEngine* NewL( const CXdmProtocolInfo& aProtocolInfo );
/**
* Fetch the IDs of the XDM Settings which have been
* configured to this device.
*
* @param RArray<TInt> On return, contains the TInt type IDs
* which correspond to the names stored
* in the returning array object.
* @return CDesC16Array* The names of the settings
*/
IMPORT_C static CDesC16Array* XdmSettingsLC( RArray<TInt>& aSettingIds );
/**
* Create a new document model
*
* @param TDesC8& Name of the document, including path
* @param TDesC8& Application usage - an AUID
*
* NOTE! It is important to keep in mind that the Xdm Engine
* DOES NOT maintain the documents created on this engine
* object. It is the responsibility of the client application
* to deallocate the documents it creates by calling
* CXdmEngine::DeleteDocumentModelL( model ). The engine
* does keep track of the documents that are constructed
* on it, but it does not own them in the sense which would
* suggest deallocation of the memory reserved for them.
*
* @return CXdmDocument instance
*/
IMPORT_C CXdmDocument* CreateDocumentModelL( const TDesC& aDocumentName,
const TXdmDocType aDocumentType );
/**
* Create a new document model
*
* @param CXdmDocument* The document model to delete
* @return void
*/
IMPORT_C void DeleteDocumentModelL( const CXdmDocument* aDocument );
/**
* Create a new document model
*
* @param CXdmDocument* The document model to delete
* @return void
*/
IMPORT_C CXdmDirectory* CreateDirectoryModelL( const TDesC& aDirectoryPath );
/**
* Create a new document model
*
* @param CXdmDocument* The document model to delete
* @return void
*/
IMPORT_C void DeleteDirectoryModelL( const CXdmDirectory* aDocument );
/**
* Create a new element.
*
* The returning CXdmDocumentNode object does not yet
* belong to any document. Therefore it is the responsibility
* of the client application to deallocate the memory
* reserved for the element.
*
* The new element can be "attached" to a document by using
* AppendToModelL() or ReplaceInModelL(). It is important to
* note that even after calling either of these methods, the
* ownership of the object does not change.
*
* @return CXdmDocumentNode*
*/
IMPORT_C CXdmDocumentNode* CreateDocumentNodeL();
/**
* Update the changes to the specified document model
*
* @param The document to be updated
* @param TRequestStatus Request status of the caller
* @return void
*/
IMPORT_C void UpdateL( CXdmDocument* aDocument,
TRequestStatus& aStatus );
/**
* Update the contents of the specified directory model
*
* @param The directory to be updated
* @param TRequestStatus Request status of the caller
* @return void
*/
IMPORT_C void UpdateL( TRequestStatus& aStatus,
CXdmDirectory* aDirectory,
TDirUpdatePhase aUpdatePhase );
/**
* Cancel an update operation on a document
*
* @param CXdmDocument The document whose update
* is being cancelled
* @return void
*/
IMPORT_C void CancelUpdate( CXdmDocument* aDocument );
/**
* Cancel an update operation on a directory
*
* @param CXdmDirectory The directory whose update
* is being cancelled
* @return void
*/
IMPORT_C void CancelUpdate( CXdmDirectory* aDirectory );
/**
* Get the list of documents created on this instance
*
* @return RPointerArray The list of document models
*/
IMPORT_C const RPointerArray<CXdmDocument>& DocumentCollection() const;
/**
* Get the list of directories created on this instance
*
* @return RPointerArray The list of document models
*/
IMPORT_C const RPointerArray<CXdmDirectory>& DirectoryCollection() const;
/**
* Destructor.
*/
IMPORT_C virtual ~CXdmEngine();
public: //New functions
/**
* Return the protocol this engine uses
*
* @return CXdmProtocol* The protocol instance
*/
CXdmProtocol* XdmProtocol() const;
/**
* Logging function
*
* @param TRefByValue<const TDesC8> aFmt,...
* @return void
*/
void WriteToLog( TRefByValue<const TDesC8> aFmt,... ) const;
public: //Static
/**
* Convert data from UNICODE to UTF-8
*
* @param TDesC& UNICODE descriptor
* @return HBufC8* Data converted to UTF-8
*/
static HBufC8* ConvertToUTF8L( const TDesC& aUnicodeDesc );
private:
/**
* C++ default constructor is private
* @return void
*/
CXdmEngine();
/**
* Symbian OS second-phase constructor
* @param CXdmProtocolInfo& Protocol information
* @return void
*/
void ConstructL( CXdmProtocolInfo& aProtocolInfo );
/**
* From CActive.
* @return void
*/
void RunL();
/**
* From CActive.
* @return void
*/
void DoCancel();
private: //Data
enum TXdmEngineState
{
EXdmEngineIdle = 0,
EXdmEngineStartDocUpdate,
EXdmEngineStartDirUpdate
};
CXdmProtocol* iXdmProtocol;
CXdmDocument* iCurrentDoc;
CXdmDirectory* iCurrentDir;
TRequestStatus* iClientStatus;
RPointerArray<CXdmDocument> iDocumentQueue;
RPointerArray<CXdmDocument> iDocUpdateQueue;
RPointerArray<CXdmDirectory> iDirUpdateQueue;
RPointerArray<CXdmDirectory> iDirectoryQueue;
CXdmLogWriter* iLogWriter;
};
#endif
// End of File