DBUtils Class Reference

#include <DBUtils.h>

Public Types
enum	{ kMagicByteCount = 8 }
typedef char	MagicBytes [kMagicByteCount]
typedef void(*	CUIDFilterFunction )(void *buffer, uint32 size, uint16 type)

Static Public Member Functions
static IDataBase *	CreateDataBase (IDataBase::UndoSupport undoSupport, bool hasContentMgr=true)
static IDataBase *	CreateCloudDataBase (IDataBase::UndoSupport undoSupport, bool hasContentMgr=true, const std::string &assetRef="")
static IDataBase *	CreateCloneFromDatabaseSnapshot (DatabaseSnapshotPtr dbSnapshot, IDataBase::UndoSupport undosupport=IDataBase::kPartialUndoSupport)
static void	SetMagicBytes (const MagicBytes bytes)
static uint32	GetAvailableNewDatabases ()
static bool16	IsValidDataBase (IDataBase *db)
static bool16	AttachInvalHandler (IDataBase *db, IInvalHandler *, InvalHandlerID id)
static void	DetachInvalHandler (IDataBase *db, IInvalHandler *)
static IInvalHandler *	GetInvalHandler (const IDataBase *db, InvalHandlerID id)
static bool16	StartCollectingInvals (IDataBase *db, IInvalHandler *handler)
static void	DiscardLazyNotificationSubject (IDataBase *db, const UIDRef &subject)
static void	SetCUIDImportFilter (CUIDFilterFunction functor)
static void	SetCUIDExportFilter (CUIDFilterFunction functor)
static CUIDFilterFunction	GetCUIDImportFilter ()
static CUIDFilterFunction	GetCUIDExportFilter ()
static BossConstructor	SetObjectConstructor (BossConstructor newConstructor)
static void	GetUIDPersistedInterfaces (IDataBase *db, UID id, ClassID clsID, IPMPersist *obj, std::vector< ImplementationID > &implList)
static void	SetBuildVersion (int32 majorVersionNumber, int32 minorVersionNumber)
static bool16	IsValidDataBase (const IDFile *fileToCheck)
static void	SetRecoveryPath (const IDFile *newPath)
static const IDFile *	GetRecoveryPath ()
static bool16	EnableInstanceCaches (bool16 enable)
static void	AddClass (IDataBase *db, ClassID newCls, UID uid)
static void	ProcessDeferredContent (IDataBase *db)
static IDataBase::CachePolicy	GetNewDataBaseCachePolicy ()
static void	SetNewDataBaseCachePolicy (IDataBase::CachePolicy)
static IRIDXDBInterface *	GetRIDXDBInterface ()
static void	SetRIDXDBInterface (IRIDXDBInterface *i)
static void	EnableRIDXDBInterface ()
static void	ShutdownSUIDS ()
static void	PreShutdownSUIDS ()
static void	InitializeSUIDS ()
static uint32	GetTotalCurrentNetworkCacheSize ()

Detailed Description

Contains static utility functions related to databases.

See Also

IDataBase

Member Typedef Documentation

typedef void(* DBUtils::CUIDFilterFunction)(void *buffer, uint32 size, uint16 type)

Internal use only.

typedef char DBUtils::MagicBytes[kMagicByteCount]

A series of 8 bytes uniquely identifies an InDesign database type; eg DOCUMENT for .indd files

Member Enumeration Documentation

anonymous enum

Enumerator
kMagicByteCount	The number of bytes in a unique identifier of an InDesign database type

Member Function Documentation

static void DBUtils::AddClass ( IDataBase *  db, ClassID  newCls, UID  uid  )

static

Internal use only.

static bool16 DBUtils::AttachInvalHandler ( IDataBase *  db, IInvalHandler *  , InvalHandlerID  id  )

static

Attach the inval handler to the database; in order for an inval handler to get notified regarding undoable transactions it must be attached to the database using this method.

The attach will fail if the database has no undo support.

The database will TAKE OWNERSHIP OF THE INVAL HANDLER POINTER. The database will delete the pointer when DetachInvalHandler is called or when the database is closed, whichever occurs first.

Parameters

db	the database to which the inval handler is to be attached
IInvalHandler*	the inval handler instance
id	unique ID (keyed off the plug-in prefix) for the inval handler

Returns

bool16 kTrue when the attach succeeds

Postcondition

The inval handler must be detached before the database is closed (see DBUtils::DetachInvalHandler).

See Also

IInvalHandler

static IDataBase* DBUtils::CreateDataBase ( IDataBase::UndoSupport  undoSupport, bool  hasContentMgr = true  )

static

Database factory function - call this to create an instance of the officially sanctioned type of database. Note that you should already have set the magic bytes for the type of database you want to create already via DBUtils::SetMagicBytes before you call this function, and reset the magic bytes to the default afterwards.

See Also

SetMagicBytes

Returns

IDataBase* the newly created database object

static void DBUtils::DetachInvalHandler ( IDataBase *  db, IInvalHandler *    )

static

Detaches the inval handler from the database and deletes the inval handler. Thus, THE INVAL HANDLER POINTER BECOMES INVALID ON FUNCTION RETURN.

Precondition

the inval handler must already be attached (see DBUtils::AttachInvalHandler)

Parameters

db
IInvalHandler*

See Also

IInvalHandler

static void DBUtils::DiscardLazyNotificationSubject ( IDataBase *  db, const UIDRef &  subject  )

static

Use of this method is very rare. It is related to lazy notifications associated with a "snapshot view interface". It is used to strip from the lazy notification queue all the lazy broadcasts associated with the "snapshot view interface" when that interface no longer targets the database to which the lazy notification queue belongs.

Parameters

db
subject	object on which the "snapshot view interface" broadcasts its changes.

static bool16 DBUtils::EnableInstanceCaches ( bool16  enable )

static

Internal use only.

static void DBUtils::EnableRIDXDBInterface ( )

static

Internal use only.

static uint32 DBUtils::GetAvailableNewDatabases ( )

static

Returns the number of additional new databases currently guaranteed to be openable without error. Current implementations of the database restrict the number of databases that may be open at any one time. If this limit is reached, the next database that you attempt to create and then IDatabase::Open() or IDatabase::New() will fail with error kTooManyFilesError. Sometimes it is useful to know beforehand how many databases you can successfully open. This function returns a value that at the time of the call guarantees a lower bound on this value (i.e. if GetAvailableNewDatabases() returns 50, then you can open 50 additional databases without getting kTooManyFilesError. You may be able to open more than the returned value in some cases).

Returns

uint32 the number of additional databases openable

static CUIDFilterFunction DBUtils::GetCUIDExportFilter ( )

static

Internal use only.

static CUIDFilterFunction DBUtils::GetCUIDImportFilter ( )

static

Internal use only.

static IInvalHandler* DBUtils::GetInvalHandler ( const IDataBase *  db, InvalHandlerID  id  )

static

Looks up the first inval handler attached to the database with the specified inval handler type id.

Parameters

db
id

static IDataBase::CachePolicy DBUtils::GetNewDataBaseCachePolicy ( )

static

Internal use only.

static const IDFile* DBUtils::GetRecoveryPath ( )

static

Internal use only.

static IRIDXDBInterface* DBUtils::GetRIDXDBInterface ( )

static

Internal use only.

static void DBUtils::GetUIDPersistedInterfaces ( IDataBase *  db, UID  id, ClassID  clsID, IPMPersist *  obj, std::vector< ImplementationID > &  implList  )

static

Returns all impls in UID that ever got persisted

static bool16 DBUtils::IsValidDataBase ( IDataBase *  db )

static

Determine if a database object pointer is still valid. This is sometimes very useful in a place where an IDataBase pointer may have been cached (such as in a scheduled command), and later you need to determine if the database is still around or whether it has already been closed/destructed.

Returns

bool16 kTrue if the database still exists, or kFalse if it has been closed/destructed and is gone.

static bool16 DBUtils::IsValidDataBase ( const IDFile *  fileToCheck )

static

Internal use only.

static void DBUtils::ProcessDeferredContent ( IDataBase *  db )

static

Internal use only.

static void DBUtils::SetBuildVersion ( int32  majorVersionNumber, int32  minorVersionNumber  )

static

Internal use only.

static void DBUtils::SetCUIDExportFilter ( CUIDFilterFunction  functor )

static

Internal use only.

static void DBUtils::SetCUIDImportFilter ( CUIDFilterFunction  functor )

static

Internal use only.

static void DBUtils::SetMagicBytes ( const MagicBytes  bytes )

static

Sets the magic bytes for the next database to be created.  Each database created has a unique

identifier of kMagicByteCount bytes that identifies its type.  Before creating a new database,

you should set the magic bytes to the identifier for your database type, and then afterwards

(regrettably) you need to remember to set it back to the default, which is "DOCUMENT" for .indd

files in InDesign.  For example:

static DBUtils::MagicBytes resetBytes = { 'D', 'O', 'C', 'U', 'M', 'E', 'N', 'T' };

static DBUtils::MagicBytes myDatabaseBytes = { ... whatever your database type uses ... };

DBUtils::SetMagicBytes(myDatabaseBytes);

IDataBase *myDB = DBUtils::CreateDataBase();

DBUtils::SetMagicBytes(resetBytes);

if (myDB) ...

Parameters

bytes

The magic bytes to set for newly constructed databases.

static void DBUtils::SetNewDataBaseCachePolicy ( IDataBase::CachePolicy  )

static

Internal use only.

static BossConstructor DBUtils::SetObjectConstructor ( BossConstructor  newConstructor )

static

Internal use only.

static void DBUtils::SetRecoveryPath ( const IDFile *  newPath )

static

Internal use only.

static void DBUtils::SetRIDXDBInterface ( IRIDXDBInterface *  i )

static

Internal use only.

static bool16 DBUtils::StartCollectingInvals ( IDataBase *  db, IInvalHandler *  handler  )

static

When an inval handler is attached to a database it can be in one of two states: 

"collecting invals" or "not collection invals". Its intial state is "not collecting invals". When in "not collecting invals", if a change to the topic of interest takes place, in order to switch to "collecting invals", the inval handler must call DBUtils::StartCollectingInvals. This call returns kTrue if there is an ongoing undoable transaction in the database and kFalse otherwise (e.g. we are in the middle of undoing). If this call returns kTrue, the inval handler switches to "collecting invals" otherwise it remains in "not collection invals".

Parameters

db
handler

Returns

kTrue if there is an ongoing undoable transaction in the database, kFalse otherwise (for example, the application is in the middle of undoing a transaction)