/******************************************************************************
 *
 * Copyright (c) 1994-2002 PalmSource, Inc. All rights reserved.
 *
 * File: DataMgr.h
 *
 * Release: Palm OS 5 SDK (68K) R2.
 *
 * Description:
 *		Header for the Data Manager
 *
 *****************************************************************************/

#ifndef __DATAMGR_H__
#define __DATAMGR_H__


// Include elementary types
#include <PalmTypes.h>					// Basic types
#include <CoreTraps.h>					// Trap Numbers.
#include <ErrorBase.h>					// Error numbers

// Other headers we depend on
#include <MemoryMgr.h>				 


typedef UInt32	DmResType;
typedef UInt16	DmResID;

/************************************************************
 * Category equates
 *************************************************************/
#define	dmRecAttrCategoryMask	0x0F	// mask for category #
#define	dmRecNumCategories		16		// number of categories
#define	dmCategoryLength			16		// 15 chars + 1 null terminator

#define  dmAllCategories			0xff
#define  dmUnfiledCategory  		0

#define	dmMaxRecordIndex			0xffff



// Record Attributes
//
// *** IMPORTANT:
// ***
// *** Any changes to record attributes must be reflected in dmAllRecAttrs and dmSysOnlyRecAttrs ***
// ***
// *** Only one nibble is available for record attributes
//
// *** ANY CHANGES MADE TO THESE ATTRIBUTES MUST BE REFLECTED IN DESKTOP LINK
// *** SERVER CODE (DLCommon.h, DLServer.c)
#define	dmRecAttrDelete			0x80	// delete this record next sync
#define	dmRecAttrDirty				0x40	// archive this record next sync
#define	dmRecAttrBusy				0x20	// record currently in use
#define	dmRecAttrSecret			0x10	// "secret" record - password protected


// All record atributes (for error-checking)
#define	dmAllRecAttrs				( dmRecAttrDelete |			\
												dmRecAttrDirty |			\
												dmRecAttrBusy |			\
												dmRecAttrSecret )

// Record attributes which only the system is allowed to change (for error-checking)
#define	dmSysOnlyRecAttrs			( dmRecAttrBusy )


/************************************************************
 * Database Header equates
 *************************************************************/
#define	dmDBNameLength				32			// 31 chars + 1 null terminator

// Attributes of a Database
//
// *** IMPORTANT:
// ***
// *** Any changes to database attributes must be reflected in dmAllHdrAttrs and dmSysOnlyHdrAttrs ***
// ***
#define	dmHdrAttrResDB					0x0001	// Resource database
#define 	dmHdrAttrReadOnly				0x0002	// Read Only database
#define	dmHdrAttrAppInfoDirty		0x0004	// Set if Application Info block is dirty
															// Optionally supported by an App's conduit
#define	dmHdrAttrBackup				0x0008	//	Set if database should be backed up to PC if
															//	no app-specific synchronization conduit has
															//	been supplied.
#define	dmHdrAttrOKToInstallNewer 	0x0010	// This tells the backup conduit that it's OK
															//  for it to install a newer version of this database
															//  with a different name if the current database is
															//  open. This mechanism is used to update the 
															//  Graffiti Shortcuts database, for example. 
#define	dmHdrAttrResetAfterInstall	0x0020 	// Device requires a reset after this database is 
															// installed.
#define	dmHdrAttrCopyPrevention		0x0040	// This database should not be copied to 

#define	dmHdrAttrStream				0x0080	// This database is used for file stream implementation.
#define	dmHdrAttrHidden				0x0100	// This database should generally be hidden from view
															//  used to hide some apps from the main view of the
															//  launcher for example.
															// For data (non-resource) databases, this hides the record
															//	 count within the launcher info screen.
#define	dmHdrAttrLaunchableData		0x0200	// This data database (not applicable for executables)
															//  can be "launched" by passing it's name to it's owner
															//  app ('appl' database with same creator) using
															//  the sysAppLaunchCmdOpenNamedDB action code. 

#define	dmHdrAttrRecyclable			0x0400	// This database (resource or record) is recyclable:
															//  it will be deleted Real Soon Now, generally the next
															//  time the database is closed. 

#define	dmHdrAttrBundle				0x0800	// This database (resource or record) is associated with
															// the application with the same creator. It will be beamed
															// and copied along with the application. 

#define	dmHdrAttrOpen					0x8000	// Database not closed properly


// All database atributes (for error-checking)
#define	dmAllHdrAttrs					(	dmHdrAttrResDB |						\
													dmHdrAttrReadOnly |					\
													dmHdrAttrAppInfoDirty |				\
													dmHdrAttrBackup |						\
													dmHdrAttrOKToInstallNewer |		\
													dmHdrAttrResetAfterInstall |		\
													dmHdrAttrCopyPrevention |			\
													dmHdrAttrStream |						\
													dmHdrAttrHidden |						\
													dmHdrAttrLaunchableData |			\
													dmHdrAttrRecyclable |				\
													dmHdrAttrBundle |						\
													dmHdrAttrOpen	)
													
// Database attributes which only the system is allowed to change (for error-checking)
#define	dmSysOnlyHdrAttrs				(	dmHdrAttrResDB |		\
													dmHdrAttrOpen	)


/************************************************************
 * Unique ID equates
 *************************************************************/
#define	dmRecordIDReservedRange		1			// The range of upper bits in the database's
															// uniqueIDSeed from 0 to this number are
															// reserved and not randomly picked when a
															// database is created.
#define	dmDefaultRecordsID			0			// Records in a default database are copied
															// with their uniqueIDSeeds set in this range.
#define	dmUnusedRecordID				0			// Record ID not allowed on the device


/************************************************************
 * Mode flags passed to DmOpenDatabase
 *************************************************************/
#define	dmModeReadOnly				0x0001		// read  access
#define	dmModeWrite					0x0002		// write access
#define	dmModeReadWrite			0x0003		// read & write access
#define	dmModeLeaveOpen			0x0004		// leave open when app quits
#define	dmModeExclusive			0x0008		// don't let anyone else open it
#define	dmModeShowSecret			0x0010		// force show of secret records

// Generic type used to represent an open Database
typedef	void *						DmOpenRef;


/************************************************************
 * Structure passed to DmGetNextDatabaseByTypeCreator and used
 *  to cache search information between multiple searches.
 *************************************************************/
typedef struct {
	UInt32		info[8];
	} DmSearchStateType;
typedef DmSearchStateType*	DmSearchStatePtr;	



/************************************************************
 * Structures used by the sorting routines
 *************************************************************/
typedef struct {
	UInt8			attributes;							// record attributes;
	UInt8			uniqueID[3];						// unique ID of record
	} SortRecordInfoType;

typedef SortRecordInfoType *SortRecordInfoPtr;

typedef Int16 DmComparF (void *, void *, Int16 other, SortRecordInfoPtr, 
								SortRecordInfoPtr, MemHandle appInfoH);



/************************************************************
 * Database manager error codes
 * the constant dmErrorClass is defined in ErrorBase.h
 *************************************************************/
#define	dmErrMemError					(dmErrorClass | 1)
#define	dmErrIndexOutOfRange			(dmErrorClass | 2)
#define	dmErrInvalidParam				(dmErrorClass | 3)
#define	dmErrReadOnly					(dmErrorClass | 4)
#define	dmErrDatabaseOpen				(dmErrorClass | 5)
#define	dmErrCantOpen					(dmErrorClass | 6)
#define	dmErrCantFind					(dmErrorClass | 7)
#define	dmErrRecordInWrongCard		(dmErrorClass | 8)
#define	dmErrCorruptDatabase			(dmErrorClass | 9)
#define	dmErrRecordDeleted			(dmErrorClass | 10)
#define	dmErrRecordArchived			(dmErrorClass | 11)
#define	dmErrNotRecordDB				(dmErrorClass | 12)
#define	dmErrNotResourceDB			(dmErrorClass | 13)
#define	dmErrROMBased					(dmErrorClass | 14)
#define	dmErrRecordBusy				(dmErrorClass | 15)
#define	dmErrResourceNotFound		(dmErrorClass | 16)
#define	dmErrNoOpenDatabase			(dmErrorClass | 17)
#define	dmErrInvalidCategory			(dmErrorClass | 18)
#define	dmErrNotValidRecord			(dmErrorClass | 19)
#define	dmErrWriteOutOfBounds		(dmErrorClass | 20)
#define	dmErrSeekFailed				(dmErrorClass | 21)
#define	dmErrAlreadyOpenForWrites	(dmErrorClass | 22)
#define	dmErrOpenedByAnotherTask	(dmErrorClass | 23)
#define  dmErrUniqueIDNotFound		(dmErrorClass | 24)
#define  dmErrAlreadyExists			(dmErrorClass | 25)
#define	dmErrInvalidDatabaseName	(dmErrorClass | 26)
#define	dmErrDatabaseProtected		(dmErrorClass | 27)
#define	dmErrDatabaseNotProtected	(dmErrorClass | 28)

/************************************************************
 * Values for the direction parameter of DmSeekRecordInCategory
 *************************************************************/
#define dmSeekForward				 1
#define dmSeekBackward				-1


/************************************************************
 * Data Manager procedures
 *************************************************************/
#ifdef __cplusplus
extern "C" {
#endif


// Initialization
Err		DmInit(void)
							SYS_TRAP(sysTrapDmInit);


// Directory Lists
Err		DmCreateDatabase(UInt16 cardNo, const Char *nameP, 
					UInt32 creator, UInt32 type, Boolean resDB)
							SYS_TRAP(sysTrapDmCreateDatabase);

Err		DmCreateDatabaseFromImage(MemPtr bufferP)
							SYS_TRAP(sysTrapDmCreateDatabaseFromImage);


Err		DmDeleteDatabase(UInt16 cardNo, LocalID dbID)
							SYS_TRAP(sysTrapDmDeleteDatabase);

UInt16	DmNumDatabases(UInt16 cardNo)
							SYS_TRAP(sysTrapDmNumDatabases);
							
LocalID	DmGetDatabase(UInt16 cardNo, UInt16 index)
							SYS_TRAP(sysTrapDmGetDatabase);

LocalID	DmFindDatabase(UInt16 cardNo, const Char *nameP)
							SYS_TRAP(sysTrapDmFindDatabase);

Err		DmGetNextDatabaseByTypeCreator(Boolean newSearch, DmSearchStatePtr stateInfoP,
			 		UInt32	type, UInt32 creator, Boolean onlyLatestVers, 
			 		UInt16 *cardNoP, LocalID *dbIDP)
							SYS_TRAP(sysTrapDmGetNextDatabaseByTypeCreator);


// Database info
Err		DmDatabaseInfo(UInt16 cardNo, LocalID	dbID, Char *nameP,
					UInt16 *attributesP, UInt16 *versionP, UInt32 *crDateP,
					UInt32 *	modDateP, UInt32 *bckUpDateP,
					UInt32 *	modNumP, LocalID *appInfoIDP,
					LocalID *sortInfoIDP, UInt32 *typeP,
					UInt32 *creatorP)
							SYS_TRAP(sysTrapDmDatabaseInfo);

Err		DmSetDatabaseInfo(UInt16 cardNo, LocalID	dbID, const Char *nameP,
					UInt16 *attributesP, UInt16 *versionP, UInt32 *crDateP,
					UInt32 *	modDateP, UInt32 *bckUpDateP,
					UInt32 *	modNumP, LocalID *appInfoIDP,
					LocalID *sortInfoIDP, UInt32 *typeP,
					UInt32 *creatorP)
							SYS_TRAP(sysTrapDmSetDatabaseInfo);

Err		DmDatabaseSize(UInt16 cardNo, LocalID dbID, UInt32 *numRecordsP,
					UInt32 *	totalBytesP, UInt32 *dataBytesP)
							SYS_TRAP(sysTrapDmDatabaseSize);
							
							
// This routine can be used to prevent a database from being deleted (by passing
//  true for 'protect'). It will increment the protect count if 'protect' is true
//  and decrement it if 'protect' is false. This is used by code that wants to
//  keep a particular record or resource in a database locked down but doesn't
//  want to keep the database open. This information is keep in the dynamic heap so
//  all databases are "unprotected" at system reset. 
Err		DmDatabaseProtect(UInt16 cardNo, LocalID dbID, Boolean protect)
							SYS_TRAP(sysTrapDmDatabaseProtect);


// Open/close Databases
DmOpenRef	DmOpenDatabase(UInt16 cardNo, LocalID dbID, UInt16 mode)
							SYS_TRAP(sysTrapDmOpenDatabase);

DmOpenRef	DmOpenDatabaseByTypeCreator(UInt32 type, UInt32 creator, UInt16 mode)
							SYS_TRAP(sysTrapDmOpenDatabaseByTypeCreator);
							
DmOpenRef	DmOpenDBNoOverlay(UInt16 cardNo, LocalID dbID, UInt16 mode)
							SYS_TRAP(sysTrapDmOpenDBNoOverlay);

Err			DmCloseDatabase(DmOpenRef dbP)
							SYS_TRAP(sysTrapDmCloseDatabase);


// Info on open databases
DmOpenRef	DmNextOpenDatabase(DmOpenRef currentP)
							SYS_TRAP(sysTrapDmNextOpenDatabase);
							
Err			DmOpenDatabaseInfo(DmOpenRef dbP, LocalID *dbIDP, 
					UInt16 *openCountP, UInt16 *modeP, UInt16 *cardNoP,
					Boolean *resDBP)
							SYS_TRAP(sysTrapDmOpenDatabaseInfo);

LocalID		DmGetAppInfoID (DmOpenRef dbP)
							SYS_TRAP(sysTrapDmGetAppInfoID);

void DmGetDatabaseLockState(DmOpenRef dbR, UInt8 *highest, UInt32 *count, UInt32 *busy)
							SYS_TRAP(sysTrapDmGetDatabaseLockState);

// Utility to unlock all records and clear busy bits
Err			DmResetRecordStates(DmOpenRef dbP)
							SYS_TRAP(sysTrapDmResetRecordStates);


// Error Query
Err			DmGetLastErr(void)
							SYS_TRAP(sysTrapDmGetLastErr);


//------------------------------------------------------------
// Record based access routines
//------------------------------------------------------------

// Record Info
UInt16	DmNumRecords(DmOpenRef dbP)
							SYS_TRAP(sysTrapDmNumRecords);

UInt16	DmNumRecordsInCategory(DmOpenRef dbP, UInt16 category)
							SYS_TRAP(sysTrapDmNumRecordsInCategory);

Err		DmRecordInfo(DmOpenRef dbP, UInt16 index,
					UInt16 *attrP, UInt32 *uniqueIDP, LocalID *chunkIDP)
							SYS_TRAP(sysTrapDmRecordInfo);

Err		DmSetRecordInfo(DmOpenRef dbP, UInt16 index,
					UInt16 *attrP, UInt32 *uniqueIDP)
							SYS_TRAP(sysTrapDmSetRecordInfo);
							


// Record attaching and detaching
Err		DmAttachRecord(DmOpenRef dbP, UInt16 *atP,
					MemHandle	newH, MemHandle *oldHP)
							SYS_TRAP(sysTrapDmAttachRecord);

Err		DmDetachRecord(DmOpenRef dbP, UInt16 index,
					MemHandle *oldHP)
							SYS_TRAP(sysTrapDmDetachRecord);
					
Err		DmMoveRecord(DmOpenRef dbP, UInt16 from, UInt16 to)
							SYS_TRAP(sysTrapDmMoveRecord);



// Record creation and deletion
MemHandle	DmNewRecord(DmOpenRef dbP, UInt16 *atP, UInt32 size)
							SYS_TRAP(sysTrapDmNewRecord);

Err		DmRemoveRecord(DmOpenRef dbP, UInt16 index)
							SYS_TRAP(sysTrapDmRemoveRecord);

Err		DmDeleteRecord(DmOpenRef dbP, UInt16 index)
							SYS_TRAP(sysTrapDmDeleteRecord);

Err		DmArchiveRecord(DmOpenRef dbP, UInt16 index)
							SYS_TRAP(sysTrapDmArchiveRecord);

MemHandle	DmNewHandle(DmOpenRef dbP, UInt32 size)
							SYS_TRAP(sysTrapDmNewHandle);

Err		DmRemoveSecretRecords(DmOpenRef dbP)
							SYS_TRAP(sysTrapDmRemoveSecretRecords);


// Record viewing manipulation
Err		DmFindRecordByID(DmOpenRef dbP, UInt32 uniqueID, UInt16 *indexP)
							SYS_TRAP(sysTrapDmFindRecordByID);

MemHandle	DmQueryRecord(DmOpenRef dbP, UInt16 index)
							SYS_TRAP(sysTrapDmQueryRecord);

MemHandle	DmGetRecord(DmOpenRef dbP, UInt16 index)
							SYS_TRAP(sysTrapDmGetRecord);
							
MemHandle	DmQueryNextInCategory(DmOpenRef dbP, UInt16 *indexP, UInt16 category)
							SYS_TRAP(sysTrapDmQueryNextInCategory);
							
UInt16	DmPositionInCategory (DmOpenRef dbP, UInt16 index, UInt16 category)
							SYS_TRAP(sysTrapDmPositionInCategory);
							
Err		DmSeekRecordInCategory (DmOpenRef dbP, UInt16 *indexP, UInt16 offset,
					Int16 direction, UInt16 category)
							SYS_TRAP(sysTrapDmSeekRecordInCategory);


MemHandle	DmResizeRecord(DmOpenRef dbP, UInt16 index, UInt32 newSize)
							SYS_TRAP(sysTrapDmResizeRecord);

Err		DmReleaseRecord(DmOpenRef dbP, UInt16 index, Boolean dirty)
							SYS_TRAP(sysTrapDmReleaseRecord);

UInt16	DmSearchRecord(MemHandle recH, DmOpenRef *dbPP)
							SYS_TRAP(sysTrapDmSearchRecord);


// Category manipulation
Err		DmMoveCategory (DmOpenRef dbP, UInt16 toCategory, UInt16 fromCategory, Boolean dirty)
							SYS_TRAP(sysTrapDmMoveCategory);

Err		DmDeleteCategory (DmOpenRef dbR, UInt16 categoryNum)
							SYS_TRAP(sysTrapDmDeleteCategory);
							
							
// Validation for writing
Err		DmWriteCheck(void *recordP, UInt32 offset, UInt32 bytes)
							SYS_TRAP(sysTrapDmWriteCheck);
							
// Writing
Err		DmWrite(void *recordP, UInt32 offset, const void *srcP, UInt32 bytes)
							SYS_TRAP(sysTrapDmWrite);
							
Err		DmStrCopy(void *recordP, UInt32 offset, const Char *srcP)
							SYS_TRAP(sysTrapDmStrCopy);

Err		DmSet(void *recordP, UInt32 offset, UInt32 bytes, UInt8 value)
							SYS_TRAP(sysTrapDmSet);
							

							

//------------------------------------------------------------
// Resource based access routines
//------------------------------------------------------------

// High level access routines
MemHandle	DmGetResource(DmResType type, DmResID resID)
							SYS_TRAP(sysTrapDmGetResource);

MemHandle	DmGet1Resource(DmResType type, DmResID resID)
							SYS_TRAP(sysTrapDmGet1Resource);

Err			DmReleaseResource(MemHandle resourceH)
							SYS_TRAP(sysTrapDmReleaseResource);

MemHandle		DmResizeResource(MemHandle resourceH, UInt32 newSize)
							SYS_TRAP(sysTrapDmResizeResource);


// Searching resource databases  
DmOpenRef	DmNextOpenResDatabase(DmOpenRef dbP)
							SYS_TRAP(sysTrapDmNextOpenResDatabase);

UInt16		DmFindResourceType(DmOpenRef dbP, DmResType resType, UInt16 typeIndex)
							SYS_TRAP(sysTrapDmFindResourceType);

UInt16		DmFindResource(DmOpenRef dbP, DmResType resType, DmResID resID, 
					MemHandle resH)
							SYS_TRAP(sysTrapDmFindResource);

UInt16		DmSearchResource(DmResType resType, DmResID resID,
					MemHandle resH, DmOpenRef *dbPP)
							SYS_TRAP(sysTrapDmSearchResource);


// Resource Info
UInt16		DmNumResources(DmOpenRef dbP)
							SYS_TRAP(sysTrapDmNumResources);

Err			DmResourceInfo(DmOpenRef dbP, UInt16 index,
					DmResType *resTypeP, DmResID *resIDP,  
					LocalID *chunkLocalIDP)
							SYS_TRAP(sysTrapDmResourceInfo);

Err			DmSetResourceInfo(DmOpenRef dbP, UInt16 index,
					DmResType *resTypeP, DmResID *resIDP)
							SYS_TRAP(sysTrapDmSetResourceInfo);



// Resource attaching and detaching
Err			DmAttachResource(DmOpenRef dbP, MemHandle	newH, 
					DmResType resType, DmResID resID)
							SYS_TRAP(sysTrapDmAttachResource);

Err			DmDetachResource(DmOpenRef dbP, UInt16 index,
					MemHandle *oldHP)
							SYS_TRAP(sysTrapDmDetachResource);



// Resource creation and deletion
MemHandle		DmNewResource(DmOpenRef dbP, DmResType resType, DmResID resID,
					UInt32 size)
							SYS_TRAP(sysTrapDmNewResource);

Err			DmRemoveResource(DmOpenRef dbP, UInt16 index)
							SYS_TRAP(sysTrapDmRemoveResource);



// Resource manipulation
MemHandle		DmGetResourceIndex(DmOpenRef dbP, UInt16 index)
							SYS_TRAP(sysTrapDmGetResourceIndex);



// Record sorting
Err 			DmQuickSort(DmOpenRef dbP, DmComparF *compar, Int16 other)
							SYS_TRAP(sysTrapDmQuickSort);

Err			DmInsertionSort (DmOpenRef dbR, DmComparF *compar, Int16 other)
							SYS_TRAP(sysTrapDmInsertionSort);

UInt16		DmFindSortPosition(DmOpenRef dbP, void *newRecord,
					SortRecordInfoPtr newRecordInfo, DmComparF *compar, Int16 other)
							SYS_TRAP(sysTrapDmFindSortPosition);

UInt16		DmFindSortPositionV10(DmOpenRef dbP, void *newRecord,
					DmComparF *compar, Int16 other)
							SYS_TRAP(sysTrapDmFindSortPositionV10);

#ifdef __cplusplus
}
#endif

#endif // __DATAMGR_H__
