diff -r 000000000000 -r dfb7c4ff071f commsfwtools/preparedefaultcommsdatabase/inc/MetaDatabase.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/commsfwtools/preparedefaultcommsdatabase/inc/MetaDatabase.h Thu Dec 17 09:22:25 2009 +0200 @@ -0,0 +1,1617 @@ +// 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 +#include + +#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS +#include +#endif + +// CommsDat headers +#include + + + +/**@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 + + 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 + + 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 + + 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 + + + + A TMDBElementId has a different format depending on the data type it expresses + + Table <0><0> + Column <0> + + Record <0> + Field + + + 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 + +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 + + 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 +
+ 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 + + @pre + + Ensure the ElementId for this container fully identifies the target data in the database +
+ 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 RefreshL(CMDBSession& aSession); + + + /** + StoreL - Store all fields in the database that have been changed in this container and + create new records where necessary. + + StoreL is atomic for this container. An internal transaction is used even if + no overall transaction is set by client. + All changed fields in the element are stored in the database on success. + No fields or records are stored in the database if the function leaves + + If a client has an open transaction in the session, the stored data will be available to this session as + soon as StoreL completes but will not be visible to other sessions until the transaction completes successfully + + 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 modify data in an unauthorised area of the database will cause the function to leave.with + KErrPermissionDenied + + If a field already exists, StoreL will leave with + KErrAlreadyExists + + May also leave with other general error codes if there are unexpected + problems (e.g. KErrNoMemory when out of memory) + + Store will be atomic - all fields stored after success. No fields stored if the function leaves + + If StoreL fails or the later commit is not successful, The data in the container will not + match the data in the database. + + On failure, the container should be discarded or repopulated before it is used again + + @pre + + Populate this container with valid data for storage + Ensure the ElementId for this container fully identifies the target location in the database +
+ 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 StoreL(CMDBSession& aSession); + + + /** + Modify all fields in the database that have been changed in this container by the caller + + Modification is atomic for this container. It uses an internal transaction even if + no overall transaction set by client. + All changed fields in the element are modified in database on success. + No fields are altered in the database if the function leaves + + Client can request to ignore access control flags by setting the attribute mask + CMDBSession::SetAttributeMask() + However, only fields that the client has capabilities to alter will be modified.in the database + A request to modify data in an unauthorised area will cause the function to 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 repopulated before it is used again + + @pre + + Populate this container with valid data for storage + Ensure the ElementId for this container fully identifies the target data in the database +
+ 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 ModifyL(CMDBSession& aSession); + + + /** + Delete fields from the database. + + Client can request to ignore access control flags by setting the attribute mask, + but only fields that the client has capabilities to delete will be removed. + + A request to delete data in unauthorised area will cause the function to leave + + @leave If client not authorised to read or write the data, will leave with + KErrPermissionDenied + May also leave with other general error codes if there are unexpected + problems (e.g. KErrNoMemory when out of memory) + + @pre Ensure the ElementId for this container fully identifies the target data in the database +
+ Ensure that the session object has appropriate access control attributes to manage the target data in the database + Ensure the ElementId for this container correcty identifies the target data in the database + + */ + IMPORT_C void DeleteL(CMDBSession& aSession); + + + /** + RequestNotification - Register for notification of events from all clients of the database + + aRequestStatus will be completed when the following events occur + TransactionComplete + TransactionRollback + SessionClose + + this aRequestStatus can be cancelled by a call to + + MMetaDatabase::CancelNotification + + all outstanding aRequestStatus can be cancelled by a call to + + CMDBSession::CancelAllNotifications + + @capability WriteDeviceData + + @return KErrNone on success. A system wide error on failure + + @params aSession a valid session object + @params aRequestStatus the requestStatus object that will be completed on notification + + @pre None + @post A notification request will be outstanding + */ + IMPORT_C TInt RequestNotification(CMDBSession& aSession, + TRequestStatus& aRequestStatus); + + /** + CancelNotification - cancel an outstanding notification request + + note that all outstanding notification requests can be cancelled by a call to + + CMDBSession::CancelAllNotifications + + @pres + + There is an outstanding notification request + + */ + IMPORT_C TInt CancelNotification(CMDBSession& aSession, + TRequestStatus& aRequestStatus); + + +protected: + + + IMPORT_C explicit MMetaDatabase(); + +private: + + /* + @internalComponent + */ + void DoLoadL(CMDBSessionImpl* aSession, CMDBElement* aElement, CMDBElement* aMapper, TInt& aErr, TMDBElementId aRecordId, TMDBElementId aAttributes, TBool isTheLoadForMapper = EFalse); + + /* + @internalComponent + */ + void DoLoadL(CMDBSessionImpl* aSession, CMDBElement* aElement, CMDBElement* aMapper, TInt& aErr, TMDBElementId aRecordId, TMDBElementId aAttributes, RArray& aMatches, TBool isTheLoadForMapper = EFalse); + + /* + @internalComponent + */ + void DoFindL(CMDBSessionImpl* aSession, CMDBElement* aElement, CMDBElement* aMapper, TInt& aErr, RArray& candidates, RArray& matches); + + /* + @internalComponent + */ + void DoRefreshL(CMDBSessionImpl* aSession, CMDBElement* aElement, CMDBElement* aMapper, TInt &aErr); + + /* + @internalComponent + */ + void DoStoreL(CMDBSessionImpl* aSession, CMDBElement* aElement, CMDBElement* aMapper, TInt &aErr); + + /* + @internalComponent + */ + void DoModifyL(CMDBSessionImpl* aSession, CMDBElement* aElement, CMDBElement* aMapper, TInt &aErr); + +}; + + + + + +class CMDBElement : public CBase, public MMetaDatabase +/** +Every item stored in the database is represented as a CMDBElement +This class contains the id and attributes of every item in the database +and for individual fields it also contains the value. + +@publishedAll +@released +*/ +{ +public: + + + /** + Default Constructor + */ + IMPORT_C CMDBElement(); + + + /** + Constructor + */ + IMPORT_C CMDBElement(TMDBElementId aElementId); + + + /** + Destructor + */ + IMPORT_C ~CMDBElement(); + + + // Accessors + + /** + Returns the ElementId of an object of this type. + + The TypeId is + + + + This identifies the meaning of the field in the database schema + It also identifies the type of the data stored in this element + and the instance of the type + + */ + IMPORT_C TMDBElementId ElementId() const; + + + /** + Returns the TypeId of an object of this type. + + The TypeId is + + + + This identifies the meaning of the data in this element in the database schema + It also identifies the type of the data contained in this element + + For an element that is a Table or a Record, the ColumnId field will be set to + + KCDMaxColumnId + */ + IMPORT_C TMDBElementId TypeId() const; + + + /** + Returns the TableId of an object of this type. + + The TableId is part of the ElementId + + + + It identifies the table in the database that holds the data contained in this element + + */ + IMPORT_C TMDBElementId TableId() const; + + + /** + Returns the RecordId of an object of this type. + + The RecordId is part of the ElementId + + It identifies a particular instance of this type of Element in the database + + */ + IMPORT_C TInt RecordId() const; + + + /** + Returns the Attributes of an object of this type. + + Attributes express database access rights for the data of this element + + */ + IMPORT_C TMDBAttributeFlags Attributes() const; + + // SETTER FUNCTIONS + + /** + Sets the ElementId + + */ + IMPORT_C void SetElementId(TMDBElementId aElementId); + + + /** + Sets the TypeId + + */ + IMPORT_C void SetTypeId(TMDBElementId aElementId); + + + /** + Sets the RecordId + + */ + IMPORT_C void SetRecordId(TInt aRecordId); + + + /** + Sets one or more attributes + + */ + IMPORT_C void SetAttributes(TMDBAttributeFlags aAttributes); + + + /** + Clears one or more attributes + + */ + IMPORT_C void ClearAttributes(TMDBAttributeFlags aAttributes); + + + /** + Queries the attributes + + Returns ETrue if all queried attributes are set + Returns EFalse if any queried attribute is not set. + */ + IMPORT_C TBool IsSetAttribute(TMDBAttributeFlags aAttributes) const; + + + /** + Queries the state of the field value + + Returns ETrue if the value of the element is not set + Returns EFalse if the element contains a value + + */ + IMPORT_C TBool IsNull() const; + + + + EXP_DATA_VTABLE + + /** + Queries the type of the field value + + Returns the enumeration TCDFieldValueTypes that represents the value that can be stored in this element + + */ + + virtual TCDFieldValueTypes Type()=0; + + /** + @internalComponent + */ + TMDBElementId* Data(){return &iElementId;} + +protected: + + TMDBElementId iElementId; + + TAny* iValue; + + }; + + + + +// +// COMMSDAT CONTAINERS +// + +/** +Commsdat Container classes qualifying numeric values +@publishedAll +*/ +class CMDBNumFieldBase : public CMDBElement +{ +public: + /** + Default Constructor + */ + IMPORT_C CMDBNumFieldBase(); + + + /** + Constructor setting Field's ElementId + */ + IMPORT_C CMDBNumFieldBase(TMDBElementId aFieldId); + + + /** + Assignment operator for field value + */ + IMPORT_C CMDBNumFieldBase& operator=(const TInt aValue); + + IMPORT_C void SetMaxLengthL(TInt aLength); + TMDBElementId GetL(); + + EXP_DATA_VTABLE + + +private: + virtual TCDFieldValueTypes Type() + { + return EInt; + } + +}; + +template +class CMDBField : public CMDBNumFieldBase +/** +A thin template that guards typed data access in a single CMDBElement +This class describes a single numeric field in the database + +@publishedAll +@released +*/ +{ +public: + + /** + Default Constructor + */ + inline CMDBField() + { + } + + /** + Constructor setting Field's ElementId + */ + inline CMDBField(TMDBElementId aFieldId) + : CMDBNumFieldBase(aFieldId) + { + } + + + /** + Assignment operator for field value + */ + inline CMDBField& operator=(const TYPE& aValue) + { + return (CMDBField&)CMDBNumFieldBase::operator=((TInt&)aValue); + } + + + inline CMDBField& operator=(const CMDBField& aValue) + { + return (CMDBField&)CMDBNumFieldBase::operator=(aValue); + } + + /** + Conversion operator for field value + */ + inline operator TYPE&() + { + return (TYPE&)iValue; + } + + /** + Conversion operator for field value + */ + inline CMDBField& GetL() + { + if(IsNull() && !(ElementId() & KCDChangedFlag)) + { + User::Leave(KErrNotFound); //todo commsdat specific error code + } + + return (TYPE&)iValue; + } + + /** + Function for setting a value + */ + inline void SetL(const TYPE& aValue) + { + CMDBNumFieldBase::operator=(aValue); + } + +}; + + + +// +/** +Base Container class qualifying a text field +@publishedAll +*/ +class CMDBTextFieldBase : public CMDBElement +{ +public: + /** + Default Constructor + */ + IMPORT_C CMDBTextFieldBase(); + + /** + Constructor setting Field's ElementId + */ + IMPORT_C CMDBTextFieldBase(TMDBElementId aFieldId); + + + /** + Destructor that deletes the field value + */ + IMPORT_C ~CMDBTextFieldBase(); + + + /** + Assignment Operator setting Field's value + */ + IMPORT_C CMDBTextFieldBase& operator=(const TDesC& aValue); + + + IMPORT_C void SetMaxLengthL(TInt aLength); + + EXP_DATA_VTABLE + +private: + virtual TCDFieldValueTypes Type() + { + return EText; + } + +}; + + + + + + + +template<> +class CMDBField : public CMDBTextFieldBase +/** +A thin template that guards typed data access in a single CMDBElement +This class describes a single field in the database + +@publishedAll +@released +*/ +{ +public: + + /** + Default Constructor + */ + inline CMDBField() + { + } + + /** + Constructor setting Field's ElementId + */ + inline CMDBField(TMDBElementId aFieldId) + : CMDBTextFieldBase(aFieldId) + { + } + + + inline void SetMaxLengthL(TInt aLength) + // create a new buffer if necessary. + { + CMDBTextFieldBase::SetMaxLengthL(aLength); + } + + inline CMDBField& operator=(const TDesC& aValue) + { + CMDBTextFieldBase::operator=(aValue); + return *this; + } + + inline CMDBField& operator=(CMDBField& aValue) + { + CMDBTextFieldBase::operator=((const TDesC&)aValue); + return *this; + } + + /** + Conversion operator for field value + */ + inline operator const TDesC&() + { + if (! iValue) + return KNullDesC; + + return *(HBufC*)iValue; + } + + /** + Conversion operator for field value + */ + inline TDesC& GetL() + { + if(IsNull() && !(ElementId() & KCDChangedFlag)) + { + User::Leave(KErrNotFound); //todo commsdat specific error code + } + + return *(HBufC*)iValue; + } + + /** + Function for setting a value + */ + inline void SetL(const TDesC& aValue) + { + SetMaxLengthL(aValue.Length()); + CMDBTextFieldBase::operator=(aValue); + } + + +}; + + +// +/** +Container class for qualifying binary values +@publishedAll +*/ +class CMDBBinFieldBase : public CMDBElement +{ +public: + /** + Default Constructor + */ + IMPORT_C CMDBBinFieldBase(); + + + /** + Constructor setting Field's ElementId + */ + IMPORT_C CMDBBinFieldBase(TMDBElementId aFieldId); + + + /** + Destructor that deletes the field value + */ + IMPORT_C ~CMDBBinFieldBase(); + + + /** + Assignment Operator setting Field's value + */ + IMPORT_C CMDBBinFieldBase& operator=(const TDesC8& aValue); + + /** + To allocate space for field data. + */ + IMPORT_C void SetMaxLengthL(TInt aLength); + + EXP_DATA_VTABLE + +private: + virtual TCDFieldValueTypes Type() + { + return EDesC8; + } +}; + + +template<> +class CMDBField : public CMDBBinFieldBase +/** +A thin template that guards typed data access in a single CMDBElement +This class describes a single field in the database + +@publishedAll +@released +*/ +{ +public: + + /** + Default Constructor + */ + inline CMDBField() + { + } + + /** + Constructor setting Field's ElementId + */ + inline CMDBField(TMDBElementId aFieldId) + : CMDBBinFieldBase(aFieldId) + { + } + + inline void SetMaxLengthL(TInt aLength) + // create a new buffer if necessary. + { + CMDBBinFieldBase::SetMaxLengthL(aLength); + } + + + inline CMDBField& operator=(const TDesC8& aValue) + { + return (CMDBField&)CMDBBinFieldBase::operator=(aValue); + } + + + inline CMDBField& operator=(CMDBField& aValue) + // Copy assignment + { + return (CMDBField&)CMDBBinFieldBase::operator=((const TDesC8&)aValue); + } + + + /** + Conversion operator for field value + */ + inline operator const TDesC8&() + { + if (! iValue) + return KNullDesC8; + + return *(HBufC8*)iValue; + } + + /** + Conversion operator for field value + */ + inline TDesC8& GetL() + { + if(IsNull() && !(ElementId() & KCDChangedFlag)) + { + User::Leave(KErrNotFound); //todo commsdat specific error code + } + + return *(HBufC8*)iValue; + } + + /** + Function for setting a value + */ + inline void SetL(const TDesC8& aValue) + { + SetMaxLengthL(aValue.Length()); + CMDBBinFieldBase::operator=(aValue); + } + +}; + + + +// + +/** +Base class for CMDBRecordLink +@publishedAll +*/ +class CMDBRecordLinkBase : public CMDBNumFieldBase +{ +public : + + IMPORT_C CMDBRecordLinkBase(); + + IMPORT_C CMDBRecordLinkBase(TMDBElementId aLinkingFieldId); + + IMPORT_C CMDBRecordLinkBase(TMDBElementId aLinkingFieldId, CMDBElement* aLinkedRecord); + + + IMPORT_C ~CMDBRecordLinkBase(); + + /** + Assignment operator for field value + which sets the id of the element list + */ + IMPORT_C CMDBRecordLinkBase& operator=(const TMDBElementId aValue); + + + /** + Conversion operator for field value + which gets the id of the element list + */ + IMPORT_C operator TMDBElementId(); + + +protected: + + EXP_DATA_VTABLE + +private: + TCDFieldValueTypes Type() + { + return ELink; + } +public: + + // the record referenced by the link id stored in the value of this field. + CMDBElement* iLinkedRecord; + +}; + + +template +class CMDBRecordLink : public CMDBRecordLinkBase +/** + This container expresses a 'soft-link' to a record in another table. + + The value of a CMDBRecordLink field as stored in the database is the + ElementId (
) of the linked record. + + The linked record itself can be viewed via the iLinkedRecord member and its accessors + + If a record is loaded then the iLinkedRecord must be created explicitly + by the client - either on construction, or by use of the CreateLinkL or + SetLinkL functions. Often the linked record is not required by a caller. + So creating it automatically would just waste memory + + However in the case of an explicit load of a LinkedRecord field the ILinkedRecord + is created. + + When instantiating iLinkedRecord directly take care to match the object's type to the Type + ID that will be found at the linking element. It is better to use the CreateLinkL or + SetLinkL functions to ensure type safety + + Calling MMetaDatabase functions on a CMDRecordLink field directly will perform the operation + on the field and also the linked record if it is present +@publishedAll +@released +*/ +{ +public : + /** + Constructor/Destructor + */ + + inline CMDBRecordLink() + : CMDBRecordLinkBase() {} + + /** + Constructor + */ + inline CMDBRecordLink(TMDBElementId aLinkingFieldId) + : CMDBRecordLinkBase(aLinkingFieldId) {} + + /** + Constructor + */ + inline CMDBRecordLink(TMDBElementId aLinkingFieldId, RECORD_TYPE* aLinkedRecord) + : CMDBRecordLinkBase(aLinkingFieldId, (CMDBElement*)aLinkedRecord) {} + + inline CMDBRecordLink& operator=(const TMDBElementId aValue) + { + return (CMDBRecordLink&)CMDBRecordLinkBase::operator=(aValue); + } + + + // SETTERS + + /** + Set the field value (this will be validated on StoreL) + */ + inline void SetL(const TMDBElementId aValue) + { + CMDBRecordLinkBase::operator=(aValue); + } + + + // OPERATORS + + /** + conversion operator for linked record of this type + */ + inline operator RECORD_TYPE*() + { + return static_cast(iLinkedRecord); + } + +}; + +enum TFieldTypeAttributes +/** +To express type information for all MetaDatabase fields +*/ + { + ENoAttrs, //< No attributes associated with this field. + ENotNull, //< Ensures the field contains a value and must not be null. + }; + +typedef struct +/** +To express type information for all MetaDatabase fields +*/ + { + const TMDBElementId iTypeId; //< Identifier for the field. + const TInt iValType; //< The field type value e.g.EText, EMedText. + const TFieldTypeAttributes iTypeAttr; //< The field attribute, either ENoAttrs or ENotNull. + const TText * const iTypeName; //< Name of the field type. + + } SRecordTypeInfo; + + +#define MDB_GENERIC_TYPE_INFO(a, b, c, d) SGenericRecordTypeInfo(a, b, c, d) + +typedef TBuf<64> TGenericTypeName; + +typedef struct SGenericRecordTypeInfoTag +/** +To express type information for all MetaDatabase fields +*/ + { + SGenericRecordTypeInfoTag() + : iTypeId(0), iValType(0), iTypeAttr(ENoAttrs) {} + + SGenericRecordTypeInfoTag(TMDBElementId aId, + TInt aVal, + TFieldTypeAttributes aAttrType) + : iTypeId(aId), iValType(aVal), iTypeAttr(aAttrType) + { + } + + SGenericRecordTypeInfoTag(TMDBElementId aId, + TInt aVal, + TFieldTypeAttributes aAttrType, + TText * const aTypeName) + : iTypeId(aId), iValType(aVal), iTypeAttr(aAttrType), iTypeName(aTypeName) + { + + } + + + SGenericRecordTypeInfoTag( TMDBElementId aId, + TInt aVal, + TFieldTypeAttributes aAttrType, + const TGenericTypeName& aTypeName) + : iTypeId(aId), iValType(aVal), iTypeAttr(aAttrType), iTypeName(aTypeName) {} + + + TMDBElementId iTypeId; //< Identifier for the field type. + TInt iValType; //< The field type value e.g.EText, EMedText. + TFieldTypeAttributes iTypeAttr; //< The type's attribute, either ENoAttrs or ENotNull + TGenericTypeName iTypeName; //< Name of the field type. + } SGenericRecordTypeInfo; + + + +class CMDBRecordBase : public CMDBNumFieldBase +/** +Base class for all MetaDatabase records +@publishedAll +@released +*/ + { + public: + + inline CMDBRecordBase(){} + inline CMDBRecordBase(TMDBElementId aElementId) + : CMDBNumFieldBase(aElementId | KCDMaskShowFieldType){} + + IMPORT_C virtual CMDBElement* GetFieldByNameL(const TPtrC& aFieldName, TInt& aValType ); + + IMPORT_C virtual CMDBElement* GetFieldByIdL(TMDBElementId aId); + + IMPORT_C virtual const SRecordTypeInfo* GetRecordInfo(); + + }; + + + +class CMDBGenericRecord : public CMDBRecordBase +/** +Container for data and type information in a MetaDatabase record +For use to contain user-defined records as an alternative to declaring a +specific record class of type CCDRecordBase + +@publishedAll +@released +*/ + { +friend class TMDBGenericRecordVisitor; +friend class CMDBSessionImpl; + public: + + + EXP_DATA_VTABLE + + explicit inline CMDBGenericRecord(TMDBElementId aElementId) + : CMDBRecordBase(aElementId) {} + + IMPORT_C ~CMDBGenericRecord(); + + IMPORT_C virtual CMDBElement* GetFieldByNameL(const TPtrC& aFieldName, TInt& aValType ); + + IMPORT_C CMDBElement* GetFieldByIdL(TMDBElementId aId); + + + IMPORT_C void InitializeL(const TDesC& aTableName, const SGenericRecordTypeInfo* aNewTableInfo); + + + private: + + /* + The name of this record type + */ + TBuf iRecordType; + + /* + array of type information about fields in this record + order of field info should match order of fields + */ + RArray iRecordInfo; + /* + array of fields in this record + order of fields should match order of field info + */ + RPointerArray iFields; + }; + + + +class CMDBRecordSetBase : public CMDBTextFieldBase +/** +Use this class to express a list of records MetaDatabase Element type +Records can be ordered using the standard RPointerArray functions + +@publishedAll +@released +*/ + { + public: + IMPORT_C CMDBRecordSetBase(); + + IMPORT_C CMDBRecordSetBase(TMDBElementId aElementId); + + IMPORT_C ~CMDBRecordSetBase(); + + inline CMDBRecordSetBase& operator=(const TPtrC& aValue) + { + return (CMDBRecordSetBase&)CMDBTextFieldBase::operator=(aValue); + } + + protected: + + EXP_DATA_VTABLE + + public: + + RPointerArray iRecords; + + }; + + + +template +class CMDBRecordSet : public CMDBRecordSetBase +/** +Use this class to express a list of records of a particular MetaDatabase Element type +Records can be ordered using the standard RPointerArray functions + +@publishedAll +@released +*/ +{ +public: + + inline CMDBRecordSet(){} + + inline CMDBRecordSet(TMDBElementId aElementId) + : CMDBRecordSetBase(aElementId) {} + + inline CMDBRecordSet& operator=(const TPtrC& aValue) + { + return (CMDBRecordSet&)CMDBRecordSetBase::operator=(aValue); + } + + inline TYPE* operator [](const TInt i) + { + return (TYPE*)iRecords[i]; + } + +private: + +}; + +} //end namespace CommsDat + +#endif // METADATABASE_H