// Copyright (c) 2004-2009 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:

// Meta-database declarations for use in storing comms data

// 

//

/**

 @file

 @publishedAll

 @released

*/

#if (!defined METADATABASE_H)

#define       METADATABASE_H

// NetMeta headers

#include <comms-infras/metadata.h>

#include <comms-infras/metatype.h>

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

#include <metadatabase_partner.h>

#endif

// CommsDat headers

#include <commsdat.h>

/**@plaintext

This file contains :

1/  Class for expressing a session with the storage server

			CMDBSession

		This class contains functions to create and close a session, to set the dataset version

		and to request database actions such as locking for a transaction.

2/  Generic database functionality interface

			MMetaDatabase

		This class uses a CMDBSession object

3/  General base class that inherits from MMetaDatabase to express any database element

			CMDBElement

		This class contains the ElementId for each MetaDatabase object

		An element id locates stored data in the comms database.

4/  Data classes that each inherit from CMDBElement

	a) Fields

			CMDBField<T>

		where T is a basic type value of the field (TInt, TDes, TBool etc)

		This class derives from

			CMDBElement

		to implement the thin template idiom

			CMDBRecordLink<T>

		where T is a record of a particular type.  This class expresses a soft-link

		from a field in one record to a record of a different type (i.e. in another table).

		The TMDBElementId value stored in this field in the repository is the id of an instance 

		of the record of type T

		This class derives from

			CMDBRecordLinkBase

		to implement the thin template idiom

	b) Field Containers

			CCDRecord

		base class for record containing specific list of fields - see CommsDatTypesv1_1.h

			CMDBRecordSet<T>

		an array of records where T is the record type.  This can represent a Table in a database.

5/  Other support classes and type definitions

			TMDBElementId

		The TMDBElementId locates a data object or set of data objects in the database.

		A TMDBElementId expresses

		<TableId><ColumnId><RecordId><Attributes>

		A TMDBElementId has a different format depending on the data type it expresses

			Table       <TableId><0><0>

			Column      <TableId><ColumnId><0>

			Record      <TableId><0><RecordId>

			Field       <TAbleId><ColumnId><RecordId>

			TMDBAttributeFlags

		Attribute settings for any storable element.

		Attributes express access control for data in the database

*/

namespace CommsDat

{

using namespace Meta;

// Private to implementation

//@internalTechnology

//@released

class CMDBSessionImpl;

// Forward declarations

class MMetaDatabase;

class CMDBElement;

/**

Attribute flags for an element in the Meta Database

Attributes describe access rights to the data in the database

@publishedAll

@released

*/

typedef TUint32         TMDBAttributeFlags;

/**

The identifier for any entry in the MetaDatabase.

It can specify

	<TableId><ColumnId><RecordId>

This identifies 

    The data location in the database

    The meaning of the data within in the data schema

    The type of the data

@publishedAll

@released

*/

typedef TUint32         TMDBElementId;

//

// COMMSDAT RECORD BASE CLASS

// Contains fields common to all records

//

	// Element Type Ids

    /** 

    Field will contain a user-defined numeric tag for a record.

    Useful for user searches and cheaper to search on a numeric tag than a string name.

    Can be null.

    This tag is not automatically connected with the record id itself,

    which is contained within the ElementId for the record and not in any field.

    @publishedAll

    @released

    */

	const TMDBElementId KCDTIdRecordTag			 = 0x00010000; 

    /**

    Field will contain a user-defined string tag for a record. 

    This is used to uniquely identify business level information within a record.

    This field is useful for user searches, however it should be noted that it would be more efficient to use the KCDTIdRecordTag field instead

    as it is quicker and cheaper to search for a number than for a string.

    @publishedAll

    @released

    */

    const TMDBElementId KCDTIdRecordName		 = 0x00020000; 

	// Element Type Names

	#define	KCDTypeNameRecordTag				_S("Id")

	#define	KCDTypeNameRecordName		        _S("Name")

class CMDBSession : public CBase

/**

A session with the underlying storage server

@publishedAll

@released

*/

{

public:

	/**

	Open a session with the storage server and establish data format version in use

	CommsDat always attempts to support the required version of the client-facing data set.

    The client must carefully choose the dataset version as it affects binary compatibility

    @params aRequiredVersion  

            If the requested version is deprecated but still supported, mapping will be performed 

            within CommsDat to maintain Data and Binary compatibility for the client

            If the requested version is the latest version, no mapping will be performed

            and deprecated fields will be ignored 

            A client that needs to maintain BC must use a specific version

            A client that always wants to use the latest dataset can start the session with KCDLatestVersion

    @leave  KErrUnsupported If an old unsupported version is requested

    @leave  System-wide error codes if there is an unexpected error

    @pre    None

    @post   on success a session has been created and initialised

	*/

	IMPORT_C static CMDBSession* NewL(TVersion aRequiredVersion);

	/**

	As NewL and adds Session to the CleanupStack

	*/

	IMPORT_C static CMDBSession* NewLC(TVersion aRequiredVersion);

	/**

	Virtual Destructor

	*/

	IMPORT_C ~CMDBSession();

	/**

	Close session with storage server.

	@publishedAll

	@deprecated v9.1 Destructor is all that is required

	*/

	IMPORT_C void Close();

	/**

	Returns the KCDCurrentVersion constant which maps to the KCDVersion1_1 

	constant for backward compatibility reason. Please avoid using this method 

	when creating a CommsDat session object and use explicit schema version 

	instead.

	@pre   None

    @post  None

	@publishedAll

	@deprecated

	*/

	IMPORT_C static TVersion LatestVersion();

	/**

	Lookup data format version currently in use by client

	*/

	IMPORT_C TVersion VersionInUse();

	/**

	Open Transaction with storage server and obtain write lock - if not already set

    @capability WriteDeviceData

    @leave	Will leave with KErrNotAvailable if Database write locked by another process

	@leave  Will report KErrAlreadyInTransaction if transaction this session is already in a transaction

    @leave  Will leave with a system-wide error code if an error occurs during commit

	@pre    None

    @post   on success the session has exclusive write access to the database

	*/

	IMPORT_C void OpenTransactionL();

	/**

	Commit Transaction in database.

    @leave	Will leave with KErrNotFound if not in transaction

    @leave  Will leave with a system-wide error code if an error occurs during commit

	@pre    None

	@post   On success the database is updated with data added, modified or deleted during the transaction

    @post   On failure, any open data containers may not be in sync with the database and should be discarded or reloaded

	*/

	IMPORT_C void CommitTransactionL();

	/**

	Cancel Transaction with database and rollback all associated changes

    @leave	Will fail with KErrNotFound if not in transaction

    @pre    None - though for correct usage, ensure a transaction is already open

	@post   Any open data containers may not be in sync with the database and should be discarded or reloaded

	*/

	IMPORT_C void RollbackTransactionL();

   /**

	Query if this session is in a transaction with the database

	Return code will indicate

		Not in transaction,

		Already in transaction for this session,

		Write-lock not available.  Another session has it.

    @pre None

	*/

	IMPORT_C TInt IsInTransaction();

    /**

	Set attributes to ignore for all database operations during this session 

    @params aAttributeFlags indicates the requested access level to stored data.

            Attributes set by this call will be ignored as restrictions in all database interactions,

	        providing the client has enough platform security capabilities to back up the request

    @pre None

	*/

	IMPORT_C void SetAttributeMask(TMDBAttributeFlags aAttributeFlags);

	/**

	Check flags in attribute mask

    @params aAttributeFlags indicates the requested access level to stored data

            Attribute flags that have been set will be ignored as restrictions in all database interactions, 

            providing the client has enough platform security capabilities to back up the request

    @return ETrue if the flag is set in the session mask 

            This means that the attribute is ignored in database interactions for this session

    @return EFalse if the flag is not set in the session mask 

            This means that the attribute is obeyed in all database interactions for this session

    @pre None

	*/

	IMPORT_C TBool IsSetAttributeMask(TMDBAttributeFlags aAttributeFlags);

    /**

	Clear attribute mask settings, indicating required access level to stored data

	Clear flags in the attribute mask for this session

        Flags indicate the requested access level to stored data

        Attribute flags that have been set in this function will be cleared from the session's 

        attribute mask and will be obeyed as restrictions in all database interactions, 

        providing the client has enough platform security capabilities to back up the request

    @pre None

	*/

	IMPORT_C void ClearAttributeMask(TMDBAttributeFlags aAttributeFlags);

	/**

	Cancel all notification requests that are outstanding from calls to 

        MMetaDatabase::RequestNotification

    Individual requests can be cancelled via MMetaDatabase::CancelNotify.

    @return KErrNone on success or a system-wide error code

    @pre  None

	*/

	IMPORT_C TInt CancelAllNotifications();

    /**

	Attempt to create publish/subscribe properties if not already defined.

        This function is normally called as a setup activity by System components

    @capability WriteDeviceData - since these properties are created in KUidSystemCategory category.  

    @return KErrNone on success.  Otherwise a system-wide error code

    @pre None

	*/	

	IMPORT_C TInt PublishProperties();

private:

    TInt ConstructL( TVersion aRequiredVersion );

	CMDBSession();

private:

	CMDBSessionImpl* iMDBSessionImpl;

	friend class MMetaDatabase;

	friend class CommsDatSchema;

};

class MMetaDatabase : public Meta::MMetaData

/**

Interface for interaction with a database server

Inherited by each data set type that can be stored

@publishedAll

@released

*/

{

public:

	IMPORT_C virtual ~MMetaDatabase();

	/**

	LoadL - Load this container with data from the database

        Any data in the container will be discarded 

        Individual fields may legitimately be NULL in the database, but if no data at all

        is found for an entire table or record, LoadL will leave with 

            KErrNotFound

        The client can request to ignore access control flags by setting the attribute mask

            CMDBSession::SetAttributeMask()

		However, only fields that the client has capabilities to write will be stored in the database

		A request to read data from an unauthorised area of the database will cause the function to leave.with 

            KErrPermissionDenied

        In a record, fields in an unauthorised column may be silently ignored and returned as NULL

        May also leave with KErrNoMemory or other general error codes

        On failure, the container should be discarded or reloaded before it is used again

    @pre

        Ensure the ElementId for this container fully identifies the target data in the database

            <Table><Column><Record>

        Ensure that the session object has been initialised with the correct dataset version

        Ensure that the session object has appropriate access control attributes to manage the target data in the database

	*/

	IMPORT_C void LoadL(CMDBSession& aSession);

	/**

	FindL - Find and Load the data set(s) that match all the data values entered by the 

    client in this container

        Client can request to ignore access control flags by setting the attribute mask,

            CMDBSession::SetAttributeMask()

		However will not load data that the client is not authorised to see (by platsec)

        even if the client has sets the appropriate attribute mask

		Will return

			ETrue on success

			EFalse if no data found that the client is authorised to view

        May also leave with KErrGeneral or other general error codes.

        On failure, the container should be discarded or repopulated before it is used again

		Please note - a case insensitive search is done in the case of text based fields

    @pre

        Populate this container where necessary with valid data to match during the find operation

        Ensure the ElementId for this container correcty identifies the target table in the database

            <Table><Column>

        Ensure that the session object has been initialised with the correct dataset version

        Ensure that the session object has appropriate access control attributes to manage the target data in the database

	 */

	IMPORT_C TBool FindL(CMDBSession& aSession);

	/**

	Refresh all fields in the container that have not been changed by the client

		The client can request to ignore access control flags by setting the attribute mask,

            CMDBSession::SetAttributeMask()

		However, only data that the client has capabilities to view will be loaded

		Unauthorised data elements will be silently ignored and will remain NULL

		If no data at all is found the functon will leave with 

			KErrNotFound

		If fields are not accessible for reading the function may leave with 

            KErrPermissionDenied

        May also leave with other general error codes if there are unexpected 

        problems (e.g. KErrNoMemory when out of memory)

        On failure, the container should be discarded or reloaded before it is used again