(****************************************************************************** * * Copyright (c) 1994-2000 Palm, Inc. or its subsidiaries. * All rights reserved. * * File: DataMgr.h * * Release: Palm OS SDK 4.0 (63220) * * Description: * Header for the Data Manager * * History: * 11/14/94 RM - Created by Ron Marianetti * *****************************************************************************) unit datamgr; interface uses palmos, coretraps, errorbase; type DmResType = UInt32; DmResID = UInt16; (************************************************************ * Category equates *************************************************************) const dmRecAttrCategoryMask = $0F; // mask for category # dmRecNumCategories = 16; // number of categories dmCategoryLength = 16; // 15 chars + 1 null terminator dmAllCategories = $ff; dmUnfiledCategory = 0; dmMaxRecordIndex = $ffff; // 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) dmRecAttrDelete = $80; // delete this record next sync dmRecAttrDirty = $40; // archive this record next sync dmRecAttrBusy = $20; // record currently in use dmRecAttrSecret = $10; // "secret" record - password protected // All record atributes (for error-checking) dmAllRecAttrs = dmRecAttrDelete or dmRecAttrDirty or dmRecAttrBusy or dmRecAttrSecret; // Record attributes which only the system is allowed to change (for error-checking) dmSysOnlyRecAttrs = dmRecAttrBusy; (************************************************************ * Database Header equates *************************************************************) dmDBNameLength = 32; // 31 chars + 1 null terminator // Attributes of a Database // // *** IMPORTANT: // *** // *** Any changes to database attributes must be reflected in dmAllHdrAttrs and dmSysOnlyHdrAttrs *** // *** dmHdrAttrResDB = $0001; // Resource database dmHdrAttrReadOnly = $0002; // Read Only database dmHdrAttrAppInfoDirty = $0004; // Set if Application Info block is dirty // Optionally supported by an App's conduit dmHdrAttrBackup = $0008; // Set if database should be backed up to PC if // no app-specific synchronization conduit has // been supplied. dmHdrAttrOKToInstallNewer = $0010; // 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. dmHdrAttrResetAfterInstall = $0020; // Device requires a reset after this database is // installed. dmHdrAttrCopyPrevention = $0040; // This database should not be copied to dmHdrAttrStream = $0080; // This database is used for file stream implementation. dmHdrAttrHidden = $0100; // 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. dmHdrAttrLaunchableData = $0200; // 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. dmHdrAttrRecyclable = $0400; // This database (resource or record) is recyclable: // it will be deleted Real Soon Now, generally the next // time the database is closed. dmHdrAttrBundle = $0800; // This database (resource or record) is associated with // the application with the same creator. It will be beamed // and copied along with the application. dmHdrAttrOpen = $8000; // Database not closed properly // All database atributes (for error-checking) dmAllHdrAttrs = dmHdrAttrResDB or dmHdrAttrReadOnly or dmHdrAttrAppInfoDirty or dmHdrAttrBackup or dmHdrAttrOKToInstallNewer or dmHdrAttrResetAfterInstall or dmHdrAttrCopyPrevention or dmHdrAttrStream or dmHdrAttrLaunchableData or dmHdrAttrRecyclable or dmHdrAttrBundle or dmHdrAttrOpen; // Database attributes which only the system is allowed to change (for error-checking) dmSysOnlyHdrAttrs = dmHdrAttrResDB or dmHdrAttrOpen; (************************************************************ * Unique ID equates *************************************************************) 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. dmDefaultRecordsID = 0; // Records in a default database are copied // with their uniqueIDSeeds set in this range. dmUnusedRecordID = 0; // Record ID not allowed on the device (************************************************************ * Mode flags passed to DmOpenDatabase *************************************************************) dmModeReadOnly = $0001; // read access dmModeWrite = $0002; // write access dmModeReadWrite = $0003; // read & write access dmModeLeaveOpen = $0004; // leave open when app quits dmModeExclusive = $0008; // don't let anyone else open it dmModeShowSecret = $0010; // force show of secret records // Generic type used to represent an open Database type DmOpenRef = Pointer; (************************************************************ * Structure passed to DmGetNextDatabaseByTypeCreator and used * to cache search information between multiple searches. *************************************************************) type DmSearchStateType = record info: array [0..8-1] of UInt32; end; DmSearchStatePtr = ^DmSearchStateType; (************************************************************ * Structures used by the sorting routines *************************************************************) SortRecordInfoType = record attributes: UInt8; // record attributes; uniqueID: array [0..3-1] of UInt8; // unique ID of record end; SortRecordInfoPtr = ^SortRecordInfoType; DmComparF = function(p1, p2: Pointer; other: Int16; s1, s2: SortRecordInfoPtr; appInfoH: MemHandle): Int16; (************************************************************ * Database manager error codes * the constant dmErrorClass is defined in ErrorBase.h *************************************************************) const dmErrMemError = dmErrorClass or 1; dmErrIndexOutOfRange = dmErrorClass or 2; dmErrInvalidParam = dmErrorClass or 3; dmErrReadOnly = dmErrorClass or 4; dmErrDatabaseOpen = dmErrorClass or 5; dmErrCantOpen = dmErrorClass or 6; dmErrCantFind = dmErrorClass or 7; dmErrRecordInWrongCard = dmErrorClass or 8; dmErrCorruptDatabase = dmErrorClass or 9; dmErrRecordDeleted = dmErrorClass or 10; dmErrRecordArchived = dmErrorClass or 11; dmErrNotRecordDB = dmErrorClass or 12; dmErrNotResourceDB = dmErrorClass or 13; dmErrROMBased = dmErrorClass or 14; dmErrRecordBusy = dmErrorClass or 15; dmErrResourceNotFound = dmErrorClass or 16; dmErrNoOpenDatabase = dmErrorClass or 17; dmErrInvalidCategory = dmErrorClass or 18; dmErrNotValidRecord = dmErrorClass or 19; dmErrWriteOutOfBounds = dmErrorClass or 20; dmErrSeekFailed = dmErrorClass or 21; dmErrAlreadyOpenForWrites = dmErrorClass or 22; dmErrOpenedByAnotherTask = dmErrorClass or 23; dmErrUniqueIDNotFound = dmErrorClass or 24; dmErrAlreadyExists = dmErrorClass or 25; dmErrInvalidDatabaseName = dmErrorClass or 26; dmErrDatabaseProtected = dmErrorClass or 27; dmErrDatabaseNotProtected = dmErrorClass or 28; (************************************************************ * Values for the direction parameter of DmSeekRecordInCategory *************************************************************) dmSeekForward = 1; dmSeekBackward = -1; (************************************************************ * Data Manager procedures *************************************************************) // Initialization function DmInit: Err; syscall sysTrapDmInit; // Directory Lists function DmCreateDatabase(cardNo: UInt16; const nameP: PChar; creator, type_: UInt32; resDB: Boolean): Err; syscall sysTrapDmCreateDatabase; function DmCreateDatabaseFromImage(bufferP: MemPtr): Err; syscall sysTrapDmCreateDatabaseFromImage; function DmDeleteDatabase(cardNo: UInt16; dbID: LocalID): Err; syscall sysTrapDmDeleteDatabase; function DmNumDatabases(cardNo: UInt16): UInt16; syscall sysTrapDmNumDatabases; function DmGetDatabase(cardNo, index: UInt16): LocalID; syscall sysTrapDmGetDatabase; function DmFindDatabase(cardNo: UInt16; const nameP: PChar): LocalID; syscall sysTrapDmFindDatabase; function DmGetNextDatabaseByTypeCreator(newSearch: Boolean; stateInfoP: DmSearchStatePtr; type_, creator: UInt32; onlyLatestVers: Boolean; var cardNoP: UInt16; var dbIDP: LocalID): Err; syscall sysTrapDmGetNextDatabaseByTypeCreator; // Database info function DmDatabaseInfo(cardNo: UInt16; dbID: LocalID; nameP: PChar; var attributesP, versionP: UInt16; var crDateP, modDateP, bckUpDateP, modNumP: UInt32; var appInfoIDP, sortInfoIDP: LocalID; var typeP, creatorP: UInt32): Err; syscall sysTrapDmDatabaseInfo; function DmSetDatabaseInfo(cardNo: UInt16; dbID: LocalID; const nameP: PChar; var attributesP, versionP: UInt16; var crDateP, modDateP, bckUpDateP, modNumP: UInt32; var appInfoIDP, sortInfoIDP: LocalID; var typeP, creatorP: UInt32): Err; syscall sysTrapDmSetDatabaseInfo; function DmDatabaseSize(cardNo: UInt16; dbID: LocalID; var numRecordsP, totalBytesP, dataBytesP: UInt32): Err; syscall 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. function DmDatabaseProtect(cardNo: UInt16; dbID: LocalID; protect: Boolean): Err; syscall sysTrapDmDatabaseProtect; // Open/close Databases function DmOpenDatabase(cardNo: UInt16; dbID: LocalID; mode: UInt16): DmOpenRef; syscall sysTrapDmOpenDatabase; function DmOpenDatabaseByTypeCreator(type_, creator: UInt32; mode: UInt16): DmOpenRef; syscall sysTrapDmOpenDatabaseByTypeCreator; function DmOpenDBNoOverlay(cardNo: UInt16; dbID: LocalID; mode: UInt16): DmOpenRef; syscall sysTrapDmOpenDBNoOverlay; function DmCloseDatabase(dbP: DmOpenRef): Err; syscall sysTrapDmCloseDatabase; // Info on open databases function DmNextOpenDatabase(currentP: DmOpenRef): DmOpenRef; syscall sysTrapDmNextOpenDatabase; function DmOpenDatabaseInfo(dbP: DmOpenRef; var dbIDP: LocalID; var openCountP, modeP, cardNoP: UInt16; var resDBP: Boolean): Err; syscall sysTrapDmOpenDatabaseInfo; function DmGetAppInfoID(dbP: DmOpenRef): LocalID; syscall sysTrapDmGetAppInfoID; procedure DmGetDatabaseLockState(dbR: DmOpenRef; var highest: UInt8; count, busy: UInt32); syscall sysTrapDmGetDatabaseLockState; // Utility to unlock all records and clear busy bits function DmResetRecordStates(dbP: DmOpenRef): Err; syscall sysTrapDmResetRecordStates; // Error Query function DmGetLastErr: Err; syscall sysTrapDmGetLastErr; //------------------------------------------------------------ // Record based access routines //------------------------------------------------------------ // Record Info function DmNumRecords(dbP: DmOpenRef): UInt16; syscall sysTrapDmNumRecords; function DmNumRecordsInCategory(dbP: DmOpenRef; category: UInt16): UInt16; syscall sysTrapDmNumRecordsInCategory; function DmRecordInfo(dbP: DmOpenRef; index: UInt16; var attrP: UInt16; var uniqueIDP: UInt32; var chunkIDP: LocalID): Err; syscall sysTrapDmRecordInfo; function DmSetRecordInfo(dbP: DmOpenRef; index: UInt16; var attrP: UInt16; var uniqueIDP: UInt32): Err; syscall sysTrapDmSetRecordInfo; // Record attaching and detaching function DmAttachRecord(dbP: DmOpenRef; var atP: UInt16; newH: MemHandle; var oldHP: MemHandle): Err; syscall sysTrapDmAttachRecord; function DmDetachRecord(dbP: DmOpenRef; index: UInt16; var oldHP: MemHandle): Err; syscall sysTrapDmDetachRecord; function DmMoveRecord(dbP: DmOpenRef; from, to_: UInt16): Err; syscall sysTrapDmMoveRecord; // Record creation and deletion function DmNewRecord(dbP: DmOpenRef; var atP: UInt16; size: UInt32): MemHandle; syscall sysTrapDmNewRecord; function DmRemoveRecord(dbP: DmOpenRef; index: UInt16): Err; syscall sysTrapDmRemoveRecord; function DmDeleteRecord(dbP: DmOpenRef; index: UInt16): Err; syscall sysTrapDmDeleteRecord; function DmArchiveRecord(dbP: DmOpenRef; index: UInt16): Err; syscall sysTrapDmArchiveRecord; function DmNewHandle(dbP: DmOpenRef; size: UInt32): MemHandle; syscall sysTrapDmNewHandle; function DmRemoveSecretRecords(dbP: DmOpenRef): Err; syscall sysTrapDmRemoveSecretRecords; // Record viewing manipulation function DmFindRecordByID(dbP: DmOpenRef; uniqueID: UInt32; var indexP: UInt16): Err; syscall sysTrapDmFindRecordByID; function DmQueryRecord(dbP: DmOpenRef; index: UInt16): MemHandle; syscall sysTrapDmQueryRecord; function DmGetRecord(dbP: DmOpenRef; index: UInt16): MemHandle; syscall sysTrapDmGetRecord; function DmQueryNextInCategory(dbP: DmOpenRef; var indexP: UInt16; category: UInt16): MemHandle; syscall sysTrapDmQueryNextInCategory; function DmPositionInCategory(dbP: DmOpenRef; index, category: UInt16): UInt16; syscall sysTrapDmPositionInCategory; function DmSeekRecordInCategory(dbP: DmOpenRef; var indexP: UInt16; offset: UInt16; direction: Int16; category: UInt16): Err; syscall sysTrapDmSeekRecordInCategory; function DmResizeRecord(dbP: DmOpenRef; index: UInt16; newSize: UInt32): MemHandle; syscall sysTrapDmResizeRecord; function DmReleaseRecord(dbP: DmOpenRef; index: UInt16; dirty: Boolean): Err; syscall sysTrapDmReleaseRecord; function DmSearchRecord(recH: MemHandle; var dbPP: DmOpenRef): UInt16; syscall sysTrapDmSearchRecord; // Category manipulation function DmMoveCategory(dbP: DmOpenRef; toCategory, fromCategory: UInt16; dirty: Boolean): Err; syscall sysTrapDmMoveCategory; function DmDeleteCategory(dbR: DmOpenRef; categoryNum: UInt16): Err; syscall sysTrapDmDeleteCategory; // Validation for writing function DmWriteCheck(recordP: Pointer; offset, bytes: UInt32): Err; syscall sysTrapDmWriteCheck; // Writing function DmWrite(recordP: Pointer; offset: UInt32; const srcP: Pointer; bytes: UInt32): Err; syscall sysTrapDmWrite; function DmStrCopy(recordP: Pointer; offset: UInt32; const srcP: PChar): Err; syscall sysTrapDmStrCopy; function DmSet(recordP: Pointer; offset, bytes: UInt32; value: UInt8): Err; syscall sysTrapDmSet; //------------------------------------------------------------ // Resource based access routines //------------------------------------------------------------ // High level access routines function DmGetResource(type_: DmResType; resID: DmResID): MemHandle; syscall sysTrapDmGetResource; function DmGet1Resource(type_: DmResType; resID: DmResID): MemHandle; syscall sysTrapDmGet1Resource; function DmReleaseResource(resourceH: MemHandle): Err; syscall sysTrapDmReleaseResource; function DmResizeResource(resourceH: MemHandle; newSize: UInt32): MemHandle; syscall sysTrapDmResizeResource; // Searching resource databases function DmNextOpenResDatabase(dbP: DmOpenRef): DmOpenRef; syscall sysTrapDmNextOpenResDatabase; function DmFindResourceType(dbP: DmOpenRef; resType: DmResType; typeIndex: UInt16): UInt16; syscall sysTrapDmFindResourceType; function DmFindResource(dbP: DmOpenRef; resType: DmResType; resID: DmResID; resH: MemHandle): UInt16; syscall sysTrapDmFindResource; function DmSearchResource(resType: DmResType; resID: DmResID; resH: MemHandle; var dbPP: DmOpenRef): UInt16; syscall sysTrapDmSearchResource; // Resource Info function DmNumResources(dbP: DmOpenRef): UInt16; syscall sysTrapDmNumResources; function DmResourceInfo(dbP: DmOpenRef; index: UInt16; var resTypeP: DmResType; var resIDP: DmResID; var chunkLocalIDP: LocalID): Err; syscall sysTrapDmResourceInfo; function DmSetResourceInfo(dbP: DmOpenRef; index: UInt16; var resTypeP: DmResType; var resIDP: DmResID): Err; syscall sysTrapDmSetResourceInfo; // Resource attaching and detaching function DmAttachResource(dbP: DmOpenRef; newH: MemHandle; resType: DmResType; resID: DmResID): Err; syscall sysTrapDmAttachResource; function DmDetachResource(dbP: DmOpenRef; index: UInt16; var oldHP: MemHandle): Err; syscall sysTrapDmDetachResource; // Resource creation and deletion function DmNewResource(dbP: DmOpenRef; resType: DmResType; resID: DmResID; size: UInt32): MemHandle; syscall sysTrapDmNewResource; function DmRemoveResource(dbP: DmOpenRef; index: UInt16): Err; syscall sysTrapDmRemoveResource; // Resource manipulation function DmGetResourceIndex(dbP: DmOpenRef; index: UInt16): MemHandle; syscall sysTrapDmGetResourceIndex; // Record sorting function DmQuickSort(dbP: DmOpenRef; compar: DmComparF; other: Int16): Err; syscall sysTrapDmQuickSort; function DmInsertionSort(dbR: DmOpenRef; compar: DmComparF; other: Int16): Err; syscall sysTrapDmInsertionSort; function DmFindSortPosition(dbP: DmOpenRef; newRecord: Pointer; newRecordInfo: SortRecordInfoPtr; compar: DmComparF; other: Int16): UInt16; syscall sysTrapDmFindSortPosition; function DmFindSortPositionV10(dbP: DmOpenRef; newRecord: Pointer; compar: DmComparF; other: Int16): UInt16; syscall sysTrapDmFindSortPositionV10; implementation end.