IDataBase.h

//========================================================================================
// 
// $File$
// 
// Owner: Roey Horns 
// 
// $Author$
// 
// $DateTime$
// 
// $Revision$
// 
// $Change$
// 
// Copyright 1997-2010 Adobe Systems Incorporated. All rights reserved.
// 
// NOTICE: Adobe permits you to use, modify, and distribute this file in accordance 
// with the terms of the Adobe license agreement accompanying it. If you have received
// this file from a source other than Adobe, then your use, modification, or 
// distribution of it requires the prior written permission of Adobe.
// 
// 
// Reviewed: 10/5/98
// 
// Purpose: Provides access to the database that holds a K2 publication.
// 
// THIS IS NOT A STANDARD BOSS INTERFACE
// 
//========================================================================================

#ifndef __IDATABASE__
#define __IDATABASE__

#include "IPMUnknown.h" // for the definition of 
#include "GlobalTime.h" // should be removed, but is indirectly included by many files
#include "IDFile.h" // for IDFile
#include "IDatabaseSnapshot.h"

class IDTime;
class IPMUnknown;
class IPubFile;
class IPMPersist;
class IDatabaseObserver;
class IUIDIterator;
class IInstanceProcessor;
class InstanceProfiler;
class IDBChangesMonitor;
class IDatabaseSnapshot;
class IDataBase
{
public:
 virtual ~IDataBase() {};
 
 typedef enum
 {
 kNoError = 0,
 kUserCanceled,
 kUnknownError,
 kLowMemoryError,
 kFileDamagedError, // file may be recoverable
 kFileCorruptError, // file is not recoverable
 kFileNotFoundError,
 kFileIsOpenError,
 kFileIsReadOnlyError,
 kDiskFullError,
 kNotFoundError,
 kFileChangedError,
 kWrongVersionError,
 kFileIsNotOpenError,
 kInvalidFileFormatError,
 kTooManyFilesError,
 kOutstandingClonesSaveError,
 kOutstandingTransactionsSaveError,
 kDBMergeFailed,
 kDBModeSwitchFailed,
 kMiniSaveFileVerificationFailedError, //temp file damaged due to MiniSave
 kUserFileVerificationFailedError, //user file damaged due to merge of tempfile
 kAccessDenied //destionation file access denied because of permission issues.
 } DBResultCode;
 
 //------------------------------------------------------------------------------------
 // Objects & UIDS
 //
 // Create, Instantiate and delete objects in the database.
 //------------------------------------------------------------------------------------
 
 virtual UID NewUID(ClassID clsID) = 0;
 virtual DBResultCode DeleteUID(UID id) = 0;
 virtual DBResultCode UndeleteUID(UID id, ClassID clsID) = 0;
 virtual DBResultCode DestroyDeletedUID(UID id) = 0;
 
 virtual IPMUnknown *Instantiate(UID id, PMIID interfaceID) = 0;

 virtual IPMUnknown *QueryInstance(UID id, PMIID interfaceID) = 0;
 
 virtual bool8 IsValidUID(UID id) const = 0;
 
 virtual UID GetRootUID() const = 0;
 virtual ClassID GetClass(UID id) const = 0; 

 virtual IUIDIterator *NewUIDIterator(bool8 includeDeletedUIDs = kFalse) const = 0;
 virtual void DeleteUIDIterator(IUIDIterator **iterator) const = 0;
 
 virtual void AssertOnModification () = 0; // Asserts if the database has been modified used to assert if the database is being dirtied on saveing.
 
 //------------------------------------------------------------------------------------
 // DataBaseObservers
 //
 // DataBaseObservers are notified for modification actions to UIDs.
 // See IDataBaseObserver.h
 //------------------------------------------------------------------------------------

 virtual void AttachDataObserver(IDatabaseObserver* observer) = 0;
 virtual void DetachDataObserver(IDatabaseObserver* observer) = 0;

 
 
 //--------------------------------------------------------------------------------------
 // DataBase File Info
 //-------------------------------------------------------------------------------------
 
 typedef enum
 {
 kSwapUnknown = 0,
 kIntelOrder, 
 kMotorolaOrder
 } ByteSwapOrder;
 
 virtual uint32 GetSaveCount() const = 0;
 virtual bool16 IsReadOnly() const = 0;
 virtual bool16 IsModified() const = 0;
 // Sets the version number of the application that was used
 // to create the database. INTERNAL USE ONLY
 virtual IDataBase::DBResultCode SetVersionNumber(const int32& majorVersion, const int32& minorVersion) = 0;
 virtual void GetVersionNumber(int32 *majorVersion, int32 *minorVersion) const = 0;
 virtual ByteSwapOrder GetByteSwap() const = 0; 
 virtual const IDFile* GetSysFile() const = 0;
 
 
 //------------------------------------------------------------------------------------
 // DataBase File Handling
 //------------------------------------------------------------------------------------
 
 typedef enum
 {
 kRead,
 kWrite,
 kCopy,
 kCopyEfficiently
 } OpenFlags;
 
 typedef enum
 {
 kSaveAs,
 kSaveACopy
 } SaveFlags;
 
 typedef enum
 {
 kDeleteAfterUse = -1,
 kNoProtection = 0, 
 kProtectSave, 
 kProtectMiniSave
 } ProtectionLevel;
 
 typedef DBResultCode (*DBProgressFunction)(int32 stepsDone, int32 stepCount);

 virtual DBResultCode New(ProtectionLevel protLevel) = 0;
 virtual DBResultCode Open(const IDFile& whatFile, ProtectionLevel protLevel,
 OpenFlags openFlag = kWrite) = 0;
 virtual DBResultCode Revert() = 0;
 virtual DBResultCode Recover(const IDFile* damagedFile, ProtectionLevel protLevel,
 ProtectionLevel oldProtLevel, const IDFile* miniSaveFile = nil) = 0;
 
 virtual DBResultCode Save() = 0;
 virtual DBResultCode SaveAs(const IDFile& destFile,
 SaveFlags saveFlag = kSaveAs) = 0;
 
 virtual void SetModified(bool16 modified) = 0;


 class SaveRestoreModifiedState
 {
 public:
 SaveRestoreModifiedState(IDataBase * db)
 : fDB(db)
 {
 if (db && db->IsModified())
 fDB = nil; // If the database is already modified we don't need to restore
 }

 ~SaveRestoreModifiedState()
 {
 if (fDB)
 fDB->SetModified(kFalse);
 }
 private:
 IDataBase * fDB;
 };
 
 virtual void SetPlatformFileInfo(void *fileInfo) = 0;

 virtual DBProgressFunction SetProgressCallback(DBProgressFunction callback) = 0;
 
 
 //--------------------------------------------------------------------------------------
 // Transactions & Mini-Save
 //
 // All changes to the database must be encapsulated in a transaction.
 // Nested transactions are possible.
 //
 // You usually do not have to call Begin/EndTransaction yourself.
 //
 // An assert regarding a database change outside of a transaction is usually 
 // caused by either a modification outside of a command, a command with
 // an incorrect target, or a command that modifies more than one database.
 //--------------------------------------------------------------------------------------
 
 virtual DBResultCode BeginTransaction() = 0;
 virtual DBResultCode EndTransaction() = 0;

 virtual int32 GetTransactionLevel() const = 0;

 virtual ProtectionLevel GetProtectionLevel() const = 0;
 virtual uint32 SetMiniSaveInterval(uint32 msecs) = 0;
 virtual uint32 GetMiniSaveInterval() const = 0;
 
 virtual const IDFile* GetMiniSaveFile() const = 0;
 
 virtual DBResultCode GetErrorCode() = 0;
 virtual void ClearError() = 0;
 
 
 //------------------------------------------------------------------------------------
 // Contiguous UID Support
 //------------------------------------------------------------------------------------

 virtual UID NewContiguousUID (uint16 type, bool16 externallyWritable) = 0;
 virtual bool16 GetContiguousUIDChangeMarker (UID id) const = 0;
 virtual void SetContiguousUIDChangeMarker (UID id, bool16 changed) = 0;

 //------------------------------------------------------------------------------------
 // For internal use only
 //------------------------------------------------------------------------------------

 virtual void DestructInstance(UID id) = 0;
 virtual void ClearDirty(IPMPersist *flushThis) = 0;
 virtual void DirtyObject(IPMPersist *flushThis, ClassID clsID, ImplementationID tag, bool16 allowModification = kTrue, bool16 firstDirtyInterface = kTrue) = 0;
 virtual void SetError(DBResultCode dbErrCode, const IDFile* userProvidedFile = nullptr) = 0;
 virtual void PurgeMemory(int32 level) = 0;
 virtual void AdviseMemoryState(int32 level) = 0;
 virtual void RegisterRootObject(IPMUnknown *root) = 0;
 virtual IPubFile* GetPubFile() = 0;
 virtual void IterateInstantiatedObjects(IInstanceProcessor *i) = 0;
 virtual InstanceProfiler *NewInstanceProfiler() = 0;
 
#ifdef DEBUG

 virtual void SetInstanceCacheState(bool16 on) = 0;
 virtual bool16 GetInstanceCacheState() = 0;
 
 virtual bool16 SetDirtyLimit(bool16 allowModification) = 0;
 virtual bool16 GetDirtyLimit() = 0;
 
 virtual bool16 BeingDestructed() = 0;
#endif

 //------------------------------------------------------------------------------------
 // Date/Time for Underlying Store
 //------------------------------------------------------------------------------------

 virtual DBResultCode GetCreationTime (IDTime &gt) = 0;

 virtual DBResultCode GetModificationTime (IDTime &gt) = 0;

 //------------------------------------------------------------------------------------
 // Save Sequence Numbers
 //------------------------------------------------------------------------------------

 virtual uint64 GetSequenceNumberAtOpen () const = 0;
 virtual uint64 GetCurrentSequenceNumber () const = 0;

 typedef enum
 {
 kUserFileExclusive = 0,
 kUserFileShared
 } UserFileMode;

 //------------------------------------------------------------------------------------
 // Cache performance. This API is for internal use only.
 //------------------------------------------------------------------------------------
 virtual uint32 GetCacheFaultRate() const = 0;
 virtual uint32 GetCacheTotalFaults() const = 0;

 enum CachePolicy
 {
 kAnnaCachePolicy,
 kFaultRateBasedPolicy,
 kCacheAllPolicy
 };

 virtual CachePolicy GetCachePolicy() const = 0;
 virtual void SetCachePolicy(CachePolicy policy) = 0;
 
 //------------------------------------------------------------------------------------
 // Support for better error handling
 //------------------------------------------------------------------------------------


 virtual const IDFile* GetSysFileFromOpen() const = 0;

 //------------------------------------------------------------------------------------
 // Snapshot Database Handler
 // Used for tracking changes to UIDs for automatic undo redo of commands. 
 //------------------------------------------------------------------------------------

 typedef enum {kNoUndoSupport, kFullUndoSupport, kPartialUndoSupport} UndoSupport;

 virtual UndoSupport GetUndoSupport() const = 0;
 
 virtual IDBChangesMonitor* GetDBChangesMonitor() const = 0;

 virtual IDatabaseSnapshot* GetLastDBSnapshotBeforePubFileSharing() const = 0;

 virtual void SetDBChangesMonitor(IDBChangesMonitor* dbChangesMonitor, UndoSupport undoSupport) = 0;

 //------------------------------------------------------------------------------------
 // Support for documents which are not datbases
 //------------------------------------------------------------------------------------
 // InCopy stores documents as XML and merely uses the database as a scratch work file.
 // As a result, assumptions about the user pubfile are invalid. The "faux" user file
 // is our way of informing the database of this situation so as to prevent problems
 // with scripting, the UI and recovery.
 virtual void SetFauxUserFile(const IDFile &newFile) = 0;
 virtual bool16 IsFauxUserFile() const = 0;

 //------------------------------------------------------------------------------------
 // More UID functions. Move up with rest between builds; but don't change vtable now [][]
 //------------------------------------------------------------------------------------
 // Creates a new persistent object in the database. The caller specifies the desired
 // UID of the new object. This will succeed under the following conditions:
 // 1. The requested UID is in the valid range - (currently: 1 <= UID <= 2^31-1)
 // 2. The UID has either never been used, or can be re-used
 // A UID that was used before can only be re-used provided that it does not exist
 // in either the temporary file or the user file. This requires at least calling
 // DeleteUID and DestoryUID, and performing a save operation afterwards if the
 // database protection level is greater than kNoProtection.
 //
 // There may be three outcomes when calling this function. Callers should be prepared:
 //
 // If the function succeeds, the object is created and the function returns kTrue
 // 
 // If the function fails because the UID isn't available to be used (outside of the
 // valid range, not available for re-use yet), the function returns kFalse but the
 // database error state is not set
 //
 // If the function fails for some more insidious reason, it returns kFalse and the 
 // database error state is set appropriately
 virtual bool16 PlacementNewUID(ClassID clsID, UID id) = 0;

 // Returns kTrue if the passed UID is valid for use/re-use with PlacementNewUID()
 virtual bool16 PlacementUIDIsAvailable (UID id) = 0;

 // Flush dirty objects for RIDX query
 virtual void FlushDirtyObjectsForRIDXQuery () = 0;

 // Clone the database
 virtual IDataBase* Clone() = 0;

 // Clone a database snapshot (for internal use only)
 virtual DatabaseSnapshotPtr CloneADatabaseSnapshot() = 0;

 // Call this function after an execution context switch took place (call from child task).
 // Necessary regardless whether the datase has been created as a clone.
 virtual bool SwitchExecutionContext() = 0;
 // Call this function before an execution context switch(call from the the parent task).
 // Not necessary if the datase has just been created as a clone
 virtual bool PrepareForExecutionContextSwitch() = 0;

 // clone must be a clone if this
 virtual DBResultCode Merge(IDataBase *clone) = 0;

 virtual DBResultCode DestroyDeletedUID_AfterLastReferenceIsReleased(UID id) = 0;

 virtual void AllowPurge() = 0;
 virtual void DisallowPurge() = 0;
 virtual void DoScheduledPurge() = 0;
 virtual bool IsPurgeAllowed() const = 0;
 
 virtual DBResultCode AttemptMiniSave() = 0;
 virtual bool PubFileIsShared() const = 0;
 
 virtual PMString GetDocumentID() = 0;
 
 /* You can override what Instantiate() does by setting an override function. Use nil to remove a function.
 SetInstantiateFunction returns the function that was previously being used, in case client code needs to
 restore it later.
 */
 struct InstantiateFunctionObj
 {
 virtual IPMUnknown* operator () (IDataBase *db, UID id, PMIID faceID) = 0;
 };

 typedef InstantiateFunctionObj* InstantiateFunction;

 virtual InstantiateFunction SetInstantiateFunction(InstantiateFunction overrideInstantiate = nil) = 0;
 virtual InstantiateFunction GetInstantiateFunction() const = 0 ;

 /* FileRecoveryMode - for internal use only */
 typedef enum {
 kNoRecovery,
 /* File opened using Pre trans master page */
 kUsingPreTransMasterPage,
 /*File opened using LPM CoWP page*/
 kUsingLPMCoWorkerPage,
 /*File opened by stripping the XMP data from file*/
 kUsingXMPDataStripping,
 /*File opened by fixing/stripping the invalid text story or parcel from file*/
 kUsingFixingInvalidTextStoryOrParcelMethod
 } FileRecoveryMode;
};


template <class T>
class DBPurgeLock
{
public:
 DBPurgeLock(T *handler) :
 fHandler(handler)
 {
 fHandler->AllowPurge();
 }
 ~DBPurgeLock()
 {
 fHandler->DisallowPurge();
 fHandler->DoScheduledPurge();
 }
private:
 T *fHandler;
};

// define adobe::type_info<IDatabase> specialization so any_regular_t can move IDataBase across DLL boundaries
ADOBE_NAME_TYPE_0("idatabase:indesign:adobe", IDataBase)

#endif // __IDATABASE__