/* * $Id: pi-dlp.h,v 1.76 2006/10/17 13:24:06 desrod Exp $ * * pi-dlp.h: Desktop Link Protocol implementation (ala SLP) * * This library is free software; you can redistribute it and/or modify it * under the terms of the GNU Library General Public License as published by * the Free Software Foundation; either version 2 of the License, or (at * your option) any later version. * * This library is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library * General Public License for more details. * * You should have received a copy of the GNU Library General Public License * along with this library; if not, write to the Free Software Foundation, * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. */ /** @file pi-dlp.h * @brief Direct protocol interface to the device using the HotSync protocol. * * The DLP layer is the lowest interface layer applications can use to * access a handheld. It provides equivalents to Palm Conduit Development * Kit (CDK)'s SyncXXX functions, as well as a number of convenience * functions that are not found in the CDK. * * Once you have a socket number and a device is connected, you can start * using DLP calls to talk with the device. All DLP calls are @b * synchronous: they are immediately sent to the device and the current * thread is blocked until either a response is received, or an error * occurs. * * It is a good pratice to always check errors returned by DLP calls. * Usually, if the value is nagative, it is an error code. If the error is * #PI_ERR_DLP_PALMOS, an error code was returned by the device itself: you * can get this error code by calling pi_palmos_error() on the current * socket. Besides all the Palm OS error code defined in Palm's * documentation, there are a few values between #dlpErrNoError and * #dlpErrUnknown which are error returned by the DLP layer itself on the * device. * * The DLP protocol is the low level protocol that HotSync uses. Over the * years, there have been several iterations of DLP. Pre-Palm OS 5 devices * have DLP 1.2 or lower. Palm OS 5 devices have DLP 1.3 or 1.4 (Palm OS 5.2 * and up). Cobalt (Palm OS 6) uses DLP 2.1. * * Devices with DLP 1.4 and later are known to support transfers of large * records and resources (of size bigger than 64k). This is the case of the * Tapwave Zodiac, for example. * * Note that some devices report an incorrect version of DLP. Some Palm OS 5 * devices report using DLP 1.2 whereas they really support DLP 1.3. * * Depending on which devices you plan on being compatible with, you should adjust * #PI_DLP_VERSION_MAJOR and #PI_DLP_VERSION_MINOR. If you want to support * devices up to and including Palm OS 5, setting your DLP version to 1.4 is * a good idea. If you want to be able to connect to Palm OS 6, you need to * set your DLP version to 2.1. */ #ifndef _PILOT_DLP_H_ #define _PILOT_DLP_H_ #ifdef __cplusplus extern "C" { #endif #include #include "pi-macros.h" /* For recordid_t */ #include "pi-buffer.h" /* For pi_buffer_t */ #include "pi-error.h" /* For PI_ERR */ /* version of the DLP protocol supported in this version */ /* Hint for existing versions: * 1.2: Palm OS 4 / Palm OS 5 (OS 5 should be 1.3 but incorrectly reports 1.2) * 1.4: TapWave Palm OS 5 * 2.1: Palm OS 6 */ #define PI_DLP_VERSION_MAJOR 1 /**< Major DLP protocol version we report to the device. */ #define PI_DLP_VERSION_MINOR 4 /**< Minor DLP protocol version we report to the device. */ #ifndef SWIG #define DLP_BUF_SIZE 0xffff /**< Kept for compatibility, applications should avoid using this value. */ #endif /* !SWIG */ /** @name Internal definitions used to assemble DLP calls */ /*@{*/ #ifndef SWIG #define PI_DLP_OFFSET_CMD 0 #define PI_DLP_OFFSET_ARGC 1 #define PI_DLP_OFFSET_ARGV 2 #define PI_DLP_ARG_TINY_LEN 0x000000FFL #define PI_DLP_ARG_SHORT_LEN 0x0000FFFFL #define PI_DLP_ARG_LONG_LEN 0xFFFFFFFFL #define PI_DLP_ARG_FLAG_TINY 0x00 #define PI_DLP_ARG_FLAG_SHORT 0x80 #define PI_DLP_ARG_FLAG_LONG 0x40 #define PI_DLP_ARG_FLAG_MASK 0xC0 #define PI_DLP_ARG_FIRST_ID 0x20 #endif /* !SWIG */ /*@}*/ /** @name VFS definitions */ /*@{*/ #define vfsMountFlagsUseThisFileSystem 0x01 /**< Mount/Format the volume with the filesystem specified */ #define vfsMAXFILENAME 256 /**< The maximum size of a filename in a VFS volume */ #define vfsInvalidVolRef 0 /**< constant for an invalid volume reference, guaranteed not to represent a valid one. Use it like you would use NULL for a FILE*. */ #define vfsInvalidFileRef 0L /**< constant for an invalid file reference, guaranteed not to represent a valid one. Use it like you would use NULL for a FILE*. */ /*@}*/ typedef unsigned long FileRef; /**< Type for file references when working with VFS files and directories. */ /** @brief Information retrieved by dlp_VFSDirEntryEnumerate() */ struct VFSDirInfo { unsigned long attr; /**< File or directory attributes (see VSF File attribute definitions) */ char name[vfsMAXFILENAME]; /**< File or directory name */ }; /** @brief Information used to format a volume with dlp_VFSVolumeFormat() */ struct VFSAnyMountParam { unsigned short volRefNum; unsigned short reserved; unsigned long mountClass; }; /** @brief Information used to format a volume with dlp_VFSVolumeFormat() */ struct VFSSlotMountParam { struct VFSAnyMountParam vfsMountParam; unsigned short slotLibRefNum; unsigned short slotRefNum; }; /** @brief Information about a VFS volume, returned by dlp_VFSVolumeInfo() */ struct VFSInfo { /* 0: read-only etc. */ unsigned long attributes; /**< Volume attributes (see #dlpVFSVolumeAttributes enum) */ /* 4: Filesystem type for this volume (defined below). These you can expect to see in devices: 'vfat' (FAT12/FAT16 with long name support) Other values observed: 'twmf' (Tapwave Zodiac internal VFS) PalmSource defines these, but don't bet on device support: 'afsu' (Andrew network filesystem) 'ext2' (Linux ext2 filesystem) 'fats' (FAT12/FAT16 with 8.3 names) 'ffsb' (BSD block-based filesystem) 'hfse' (Macintosh HFS+) 'hfss' (Macintosh HFS, pre-8.x) 'hpfs' (OS/2 High Performance Filesystem) 'mfso' (Original Macintosh filesystem) 'nfsu' (NFS mount) 'novl' (Novell filesystem) 'ntfs' (Windows NT filesystem) */ unsigned long fsType; /**< File system time (four-char code, see above) */ /* 8: Creator code of filesystem driver for this volume. */ unsigned long fsCreator; /**< File system creator (four-char code) */ /* For slot based filesystems: (mountClass = VFSMountClass_SlotDriver) 12: mount class that mounted this volume */ unsigned long mountClass; /**< Mount class */ /* 16: Library on which the volume is mounted */ int slotLibRefNum; /**< Slot library reference number */ /* 18: ExpMgr slot number of card containing volume */ int slotRefNum; /**< Expansion manager slot number */ /* 20: Type of card media (mediaMemoryStick, mediaCompactFlash, etc.) These you can expect to see in devices: 'cfsh' (CompactFlash) 'mmcd' (MultiMedia Card) 'mstk' (Memory Stick) 'sdig' (SD card) Other values observed: 'TFFS' (palmOne Tungsten T5 internal VFS) 'twMF' (Tapwave Zodiac internal VFS) PalmSource also defines these: 'pose' (Host filesystem emulated by POSE) 'PSim' (Host filesystem emulated by Mac Simulator) 'ramd' (RAM disk) 'smed' (SmartMedia) */ unsigned long mediaType; /**< Media type (see above) */ /* 24: reserved for future use (other mountclasses may need more space) */ unsigned long reserved; /**< Reserved, set to 0 */ }; /** @brief Information about the handheld user * * This structure is used in dlp_ReadUserInfo() and dlp_WriteUserInfo() */ struct PilotUser { size_t passwordLength; char username[128]; char password[128]; unsigned long userID; unsigned long viewerID; unsigned long lastSyncPC; time_t successfulSyncDate; time_t lastSyncDate; }; /** @brief Device information. * * This structure is filled by dlp_ReadSysInfo() */ struct SysInfo { unsigned long romVersion; /**< Version of the device ROM, of the form 0xMMmmffssbb where MM=Major, mm=minor, ff=fix, ss=stage, bb=build */ unsigned long locale; /**< Locale for this device */ unsigned char prodIDLength; /**< Length of the prodID string */ char prodID[128]; /**< Product ID */ unsigned short dlpMajorVersion; /**< Major version of the DLP protocol on this device */ unsigned short dlpMinorVersion; /**< Minor version of the DLP protocol on this device */ unsigned short compatMajorVersion; /**< Minimum major version of DLP this device is compatible with */ unsigned short compatMinorVersion; /**< Minimum minor version of DLP this device is compatible with */ unsigned long maxRecSize; /**< Maximum record size. Usually <=0xFFFF or ==0 for older devices (means records are limited to 64k), can be much larger for devices with DLP >= 1.4 (i.e. 0x00FFFFFE) */ }; /** @brief Database information. * * A database information block is returned by dlp_ReadDBList(), dlp_FindDBInfo(), dlp_FindDBByName(), dlp_FindDBByOpenHandle() * and dlp_FindDBByTypeCreator(). */ struct DBInfo { int more; /**< When reading database list using dlp_ReadDBList(), this flag is set if there are more databases to come */ char name[34]; /**< Database name, 32 characters max. */ unsigned int flags; /**< Database flags (@see dlpDBFlags enum) */ unsigned int miscFlags; /**< Additional database flags filled by pilot-link (@see dlpDBMiscFlags enum) */ unsigned int version; /**< Database version number */ unsigned long type; /**< Database type (four-char code, i.e. 'appl') */ unsigned long creator; /**< Database creator (four-char code, i.e. 'DATA') */ unsigned long modnum; /**< Modification count */ unsigned int index; /**< Database index in database list */ time_t createDate; /**< Database creation date (using the machine's local time zone) */ time_t modifyDate; /**< Last time this database was modified (using the machine's local time zone). If the database was never modified, this field is set to 0x83DAC000 (Fri Jan 1 00:00:00 1904 GMT) */ time_t backupDate; /**< Last time this database was backed up using HotSync. If the database was never backed up, this field is set to 0x83DAC000 (Fri Jan 1 00:00:00 1904 GMT) */ }; /** @brief Size information for a database. * * Returned by dlp_FindDBByName(), dlp_FindDBByOpenHandle() and dlp_FindDBByTypeCreator(). */ struct DBSizeInfo { unsigned long numRecords; /**< Number of records or resources */ unsigned long totalBytes; /**< Total number of bytes occupied by the database, including header and records list */ unsigned long dataBytes; /**< Total number of data bytes contained in the database's records or resources */ unsigned long appBlockSize; /**< Size of the appInfo block */ unsigned long sortBlockSize; /**< Size of the sortInfo block */ unsigned long maxRecSize; /**< note: this field is always set to 0 on return from dlp_FindDBxxx */ }; /** @brief Information about a memory card. * * This structure describes a device's internal storage only, not removable media. * It is returned by dlp_ReadStorageInfo(). */ struct CardInfo { int card; /**< Memory card index (most devices only have one). */ int version; /**< Version of the card */ int more; /**< Set if there is another card after this one */ time_t creation; /**< Creation date (using the computer's local time zone) */ unsigned long romSize; /**< Size of the ROM block on this card (in bytes) */ unsigned long ramSize; /**< Size of the RAM block on this card (in bytes) */ unsigned long ramFree; /**< Total free RAM bytes */ char name[128]; /**< Card name */ char manufacturer[128]; /**< Card manufacturer name */ }; /** @brief Network HotSync information. * * Returned by dlp_ReadNetSyncInfo(). Gives the network location of a remote handheld. */ struct NetSyncInfo { int lanSync; /**< Non-zero if LanSync is turned on on the device */ char hostName[256]; /**< Device hostname if any. Null terminated string. */ char hostAddress[40]; /**< Device host address. Null terminated string. */ char hostSubnetMask[40]; /**< Device subnet mask. Null terminated string */ }; #ifndef SWIG /* no need to clutter the bindings with this */ enum dlpFunctions { /* range reserved for internal use */ dlpReservedFunc = 0x0F, /* DLP 1.0 FUNCTIONS START HERE (PalmOS v1.0) */ dlpFuncReadUserInfo, /* 0x10 */ dlpFuncWriteUserInfo, /* 0x11 */ dlpFuncReadSysInfo, /* 0x12 */ dlpFuncGetSysDateTime, /* 0x13 */ dlpFuncSetSysDateTime, /* 0x14 */ dlpFuncReadStorageInfo, /* 0x15 */ dlpFuncReadDBList, /* 0x16 */ dlpFuncOpenDB, /* 0x17 */ dlpFuncCreateDB, /* 0x18 */ dlpFuncCloseDB, /* 0x19 */ dlpFuncDeleteDB, /* 0x1a */ dlpFuncReadAppBlock, /* 0x1b */ dlpFuncWriteAppBlock, /* 0x1c */ dlpFuncReadSortBlock, /* 0x1d */ dlpFuncWriteSortBlock, /* 0x1e */ dlpFuncReadNextModifiedRec, /* 0x1f */ dlpFuncReadRecord, /* 0x20 */ dlpFuncWriteRecord, /* 0x21 */ dlpFuncDeleteRecord, /* 0x22 */ dlpFuncReadResource, /* 0x23 */ dlpFuncWriteResource, /* 0x24 */ dlpFuncDeleteResource, /* 0x25 */ dlpFuncCleanUpDatabase, /* 0x26 */ dlpFuncResetSyncFlags, /* 0x27 */ dlpFuncCallApplication, /* 0x28 */ dlpFuncResetSystem, /* 0x29 */ dlpFuncAddSyncLogEntry, /* 0x2a */ dlpFuncReadOpenDBInfo, /* 0x2b */ dlpFuncMoveCategory, /* 0x2c */ dlpProcessRPC, /* 0x2d */ dlpFuncOpenConduit, /* 0x2e */ dlpFuncEndOfSync, /* 0x2f */ dlpFuncResetRecordIndex, /* 0x30 */ dlpFuncReadRecordIDList, /* 0x31 */ /* DLP 1.1 FUNCTIONS ADDED HERE (PalmOS v2.0 Personal, and Professional) */ dlpFuncReadNextRecInCategory, /* 0x32 */ dlpFuncReadNextModifiedRecInCategory, /* 0x33 */ dlpFuncReadAppPreference, /* 0x34 */ dlpFuncWriteAppPreference, /* 0x35 */ dlpFuncReadNetSyncInfo, /* 0x36 */ dlpFuncWriteNetSyncInfo, /* 0x37 */ dlpFuncReadFeature, /* 0x38 */ /* DLP 1.2 FUNCTIONS ADDED HERE (PalmOS v3.0) */ dlpFuncFindDB, /* 0x39 */ dlpFuncSetDBInfo, /* 0x3a */ /* DLP 1.3 FUNCTIONS ADDED HERE (PalmOS v4.0) */ dlpLoopBackTest, /* 0x3b */ dlpFuncExpSlotEnumerate, /* 0x3c */ dlpFuncExpCardPresent, /* 0x3d */ dlpFuncExpCardInfo, /* 0x3e */ dlpFuncVFSCustomControl, /* 0x3f */ dlpFuncVFSGetDefaultDir, /* 0x40 */ dlpFuncVFSImportDatabaseFromFile, /* 0x41 */ dlpFuncVFSExportDatabaseToFile, /* 0x42 */ dlpFuncVFSFileCreate, /* 0x43 */ dlpFuncVFSFileOpen, /* 0x44 */ dlpFuncVFSFileClose, /* 0x45 */ dlpFuncVFSFileWrite, /* 0x46 */ dlpFuncVFSFileRead, /* 0x47 */ dlpFuncVFSFileDelete, /* 0x48 */ dlpFuncVFSFileRename, /* 0x49 */ dlpFuncVFSFileEOF, /* 0x4a */ dlpFuncVFSFileTell, /* 0x4b */ dlpFuncVFSFileGetAttributes, /* 0x4c */ dlpFuncVFSFileSetAttributes, /* 0x4d */ dlpFuncVFSFileGetDate, /* 0x4e */ dlpFuncVFSFileSetDate, /* 0x4f */ dlpFuncVFSDirCreate, /* 0x50 */ dlpFuncVFSDirEntryEnumerate, /* 0x51 */ dlpFuncVFSGetFile, /* 0x52 */ dlpFuncVFSPutFile, /* 0x53 */ dlpFuncVFSVolumeFormat, /* 0x54 */ dlpFuncVFSVolumeEnumerate, /* 0x55 */ dlpFuncVFSVolumeInfo, /* 0x56 */ dlpFuncVFSVolumeGetLabel, /* 0x57 */ dlpFuncVFSVolumeSetLabel, /* 0x58 */ dlpFuncVFSVolumeSize, /* 0x59 */ dlpFuncVFSFileSeek, /* 0x5a */ dlpFuncVFSFileResize, /* 0x5b */ dlpFuncVFSFileSize, /* 0x5c */ /* DLP 1.4 functions added here (Palm OS 5.2+, ie Tapwave Zodiac) */ dlpFuncExpSlotMediaType, /* 0x5d */ dlpFuncWriteRecordEx, /* 0x5e - function to write >64k records in Tapwave */ dlpFuncWriteResourceEx, /* 0x5f - function to write >64k resources in Tapwave */ dlpFuncReadRecordEx, /* 0x60 - function to read >64k records by index in Tapwave */ dlpFuncUnknown1, /* 0x61 (may be bogus definition in tapwave headers, is listed as dlpFuncReadRecordStream)*/ dlpFuncUnknown3, /* 0x62 */ dlpFuncUnknown4, /* 0x63 */ dlpFuncReadResourceEx, /* 0x64 - function to read resources >64k by index in Tapwave */ dlpLastFunc }; #endif /* !SWIG */ /** @name Database and record attributes */ /*@{*/ /** @brief Database flags in DBInfo structure and also for dlp_CreateDB() */ enum dlpDBFlags { dlpDBFlagResource = 0x0001, /**< Resource database */ dlpDBFlagReadOnly = 0x0002, /**< Database is read only */ dlpDBFlagAppInfoDirty = 0x0004, /**< AppInfo data has been modified */ dlpDBFlagBackup = 0x0008, /**< Database should be backed up during HotSync */ dlpDBFlagHidden = 0x0100, /**< Database is hidden */ dlpDBFlagLaunchable = 0x0200, /**< Database is launchable data (show in Launcher, launch app by Creator) */ dlpDBFlagRecyclable = 0x0400, /**< Database will be deleted shortly */ dlpDBFlagBundle = 0x0800, /**< Database is bundled with others having same creator (i.e. for Beam) */ dlpDBFlagOpen = 0x8000, /**< Database is currently open */ /* v2.0 specific */ dlpDBFlagNewer = 0x0010, /**< Newer version may be installed over open DB (Palm OS 2.0 and later) */ dlpDBFlagReset = 0x0020, /**< Reset after installation (Palm OS 2.0 and later) */ /* v3.0 specific */ dlpDBFlagCopyPrevention = 0x0040, /**< Database should not be beamed or sent (Palm OS 3.0 and later) */ dlpDBFlagStream = 0x0080, /**< Database is a file stream (Palm OS 3.0 and later) */ /* OS 6+ */ dlpDBFlagSchema = 0x1000, /**< Schema database (Palm OS 6.0 and later) */ dlpDBFlagSecure = 0x2000, /**< Secure database (Palm OS 6.0 and later) */ dlpDBFlagExtended = dlpDBFlagSecure, /**< Set if Schema not set and DB is Extended (Palm OS 6.0 and later) */ dlpDBFlagFixedUp = 0x4000 /**< Temp flag used to clear DB on write (Palm OS 6.0 and later) */ }; /** @brief Misc. flags in DBInfo structure */ enum dlpDBMiscFlags { dlpDBMiscFlagExcludeFromSync = 0x80, /**< DLP 1.1 and later: exclude this database from sync */ dlpDBMiscFlagRamBased = 0x40 /**< DLP 1.2 and later: this database is in RAM */ }; /** @brief Database record attributes */ enum dlpRecAttributes { dlpRecAttrDeleted = 0x80, /**< Tagged for deletion during next sync */ dlpRecAttrDirty = 0x40, /**< Record modified */ dlpRecAttrBusy = 0x20, /**< Record locked (in use) */ dlpRecAttrSecret = 0x10, /**< Record is secret */ dlpRecAttrArchived = 0x08 /**< Tagged for archival during next sync */ }; /** @brief Mode flags used in dlp_OpenDB() */ enum dlpOpenFlags { dlpOpenRead = 0x80, /**< Open database for reading */ dlpOpenWrite = 0x40, /**< Open database for writing */ dlpOpenExclusive = 0x20, /**< Open database with exclusive access */ dlpOpenSecret = 0x10, /**< Show secret records */ dlpOpenReadWrite = 0xC0 /**< Open database for reading and writing (equivalent to (#dlpOpenRead | #dlpOpenWrite)) */ }; /** @brief Flags passed to dlp_ReadDBList() */ enum dlpDBList { dlpDBListRAM = 0x80, /**< List RAM databases */ dlpDBListROM = 0x40, /**< List ROM databases */ dlpDBListMultiple = 0x20 /**< DLP 1.2 and above: list as many databases as possible at once */ }; enum dlpFindDBOptFlags { dlpFindDBOptFlagGetAttributes = 0x80, dlpFindDBOptFlagGetSize = 0x40, dlpFindDBOptFlagMaxRecSize = 0x20 }; enum dlpFindDBSrchFlags { dlpFindDBSrchFlagNewSearch = 0x80, dlpFindDBSrchFlagOnlyLatest = 0x40 }; /*@}*/ /** @brief End status values for dlp_EndOfSync() */ enum dlpEndStatus { dlpEndCodeNormal = 0, /**< Normal termination */ dlpEndCodeOutOfMemory, /**< End due to low memory on device */ dlpEndCodeUserCan, /**< Cancelled by user */ dlpEndCodeOther /**< dlpEndCodeOther and higher == "Anything else" */ }; /** @name Expansion manager and VFS manager constants */ /*@{*/ /** @brief Expansion card capabilities, as returned by dlp_ExpCardInfo() */ enum dlpExpCardCapabilities { dlpExpCapabilityHasStorage = 0x00000001, /**< Card supports reading (and maybe writing) */ dlpExpCapabilityReadOnly = 0x00000002, /**< Card is read-only */ dlpExpCapabilitySerial = 0x00000004 /**< Card supports dumb serial interface */ }; /** @brief VFS volume attributes as found in the @a attributes member of a VFSInfo structure */ enum dlpVFSVolumeAttributes { vfsVolAttrSlotBased = 0x00000001, /**< Volume is inserted is an expansion slot */ vfsVolAttrReadOnly = 0x00000002, /**< Volume is read-only */ vfsVolAttrHidden = 0x00000004 /**< Volume is hidden */ }; /** @brief Constants for dlp_VFSFileSeek() */ enum dlpVFSSeekConstants { vfsOriginBeginning = 0, /**< From the beginning (first data byte of file) */ vfsOriginCurrent = 1, /**< from the current position */ vfsOriginEnd = 2 /**< From the end of file (one position beyond last data byte, only negative offsets are legally allowed) */ }; /** @brief Flags for dlp_VFSFileOpen() */ enum dlpVFSOpenFlags { dlpVFSOpenExclusive = 0x01, /**< For dlp_VFSFileOpen(). Exclusive access */ dlpVFSOpenRead = 0x02, /**< For dlp_VFSFileOpen(). Read only */ dlpVFSOpenWrite = 0x05, /**< For dlp_VFSFileOpen(). Write only. Implies exclusive */ dlpVFSOpenReadWrite = 0x07, /**< For dlp_VFSFileOpen(). Read | write */ /* Remainder are aliases and special cases not for VFSFileOpen */ vfsModeExclusive = dlpVFSOpenExclusive, /**< Alias to #dlpVFSOpenExclusive */ vfsModeRead = dlpVFSOpenRead, /**< Alias to #dlpVFSOpenRead */ vfsModeWrite = dlpVFSOpenWrite, /**< Alias to #dlpVFSOpenWrite */ vfsModeReadWrite = vfsModeRead | vfsModeWrite, /**< Alias to #dlpVFSOpenReadWrite */ vfsModeCreate = 0x08 /**< Not for dlp_VFSFileOpen(). Create file if it doesn't exist. */, vfsModeTruncate = 0x10 /**< Not for dlp_VFSFileOpen(). Truncate to 0 bytes on open. */, vfsModeLeaveOpen = 0x20 /**< Not for dlp_VFSFileOpen(). Leave file open even if foreground task closes. */ } ; /** @brief VFS file attribute constants */ enum dlpVFSFileAttributeConstants { vfsFileAttrReadOnly = 0x00000001, /**< File is read only */ vfsFileAttrHidden = 0x00000002, /**< File is hidden */ vfsFileAttrSystem = 0x00000004, /**< File is a system file */ vfsFileAttrVolumeLabel = 0x00000008, /**< File is the volume label */ vfsFileAttrDirectory = 0x00000010, /**< File is a directory */ vfsFileAttrArchive = 0x00000020, /**< File is archived */ vfsFileAttrLink = 0x00000040 /**< File is a link to another file */ }; /** @brief Constants for dlp_VFSFileGetDate() and dlp_VFSFileSetDate() */ enum dlpVFSDateConstants { vfsFileDateCreated = 1, /**< The date the file was created. */ vfsFileDateModified = 2, /**< The date the file was last modified. */ vfsFileDateAccessed = 3 /**< The date the file was last accessed. */ }; /** @brief VFS file iterator constants */ enum dlpVFSFileIteratorConstants { vfsIteratorStart = 0, /** < Indicates that iterator is beginning */ vfsIteratorStop = -1 /**< Indicate that iterator has gone through all items */ }; /*@}*/ /** @brief Error codes returned by DLP transactions * * After a DLP transaction, there may be a DLP or Palm OS error * if the result code is #PI_ERR_DLP_PALMOS. In this case, use * pi_palmos_error() to obtain the error code. It can be in the * DLP error range (0 > error < #dlpErrLastError), or otherwise * in the Palm OS error range (see Palm OS header files for * definitions, in relation with each DLP call) */ enum dlpErrors { dlpErrNoError = 0, /**< No error */ dlpErrSystem, /**< System error (0x0001) */ dlpErrIllegalReq, /**< Illegal request, not supported by this version of DLP (0x0002) */ dlpErrMemory, /**< Not enough memory (0x0003) */ dlpErrParam, /**< Invalid parameter (0x0004) */ dlpErrNotFound, /**< File, database or record not found (0x0005) */ dlpErrNoneOpen, /**< No file opened (0x0006) */ dlpErrAlreadyOpen, /**< File already open (0x0007) */ dlpErrTooManyOpen, /**< Too many open files (0x0008) */ dlpErrExists, /**< File already exists (0x0009) */ dlpErrOpen, /**< Can't open file (0x000a) */ dlpErrDeleted, /**< File deleted (0x000b) */ dlpErrBusy, /**< Record busy (0x000c) */ dlpErrNotSupp, /**< Call not supported (0x000d) */ dlpErrUnused1, /**< @e Unused (0x000e) */ dlpErrReadOnly, /**< File is read-only (0x000f) */ dlpErrSpace, /**< Not enough space left on device (0x0010) */ dlpErrLimit, /**< Limit reached (0x0011) */ dlpErrSync, /**< Sync error (0x0012) */ dlpErrWrapper, /**< Wrapper error (0x0013) */ dlpErrArgument, /**< Invalid argument (0x0014) */ dlpErrSize, /**< Invalid size (0x0015) */ dlpErrUnknown = 127 /**< Unknown error (0x007F) */ }; #ifndef SWIG /* no need to clutter the bindings with this */ /** @brief Internal DLP argument structure */ struct dlpArg { int id_; /**< Argument ID (start at #PI_DLP_ARG_FIRST_ID) */ size_t len; /**< Argument length */ char *data; /**< Argument data */ }; /** @brief Internal DLP command request structure */ struct dlpRequest { enum dlpFunctions cmd; /**< Command ID */ int argc; /**< Number of arguments */ struct dlpArg **argv; /**< Ptr to arguments */ }; /** @brief Internal DLP command response structure */ struct dlpResponse { enum dlpFunctions cmd; /**< Command ID as returned by device. If not the same than requested command, this is an error */ enum dlpErrors err; /**< DLP error (see #dlpErrors enum) */ int argc; /**< Number of response arguments */ struct dlpArg **argv; /**< Response arguments */ }; #endif /* !SWIG */ /* @name Functions used internally by dlp.c */ /*@{*/ #ifndef SWIG /* don't export these functions to bindings */ extern struct dlpArg * dlp_arg_new PI_ARGS((int id_, size_t len)); extern void dlp_arg_free PI_ARGS((struct dlpArg *arg)); extern int dlp_arg_len PI_ARGS((int argc, struct dlpArg **argv)); extern struct dlpRequest *dlp_request_new PI_ARGS((enum dlpFunctions cmd, int argc, ...)); extern struct dlpRequest * dlp_request_new_with_argid PI_ARGS((enum dlpFunctions cmd, int argid, int argc, ...)); extern void dlp_request_free PI_ARGS((struct dlpRequest *req)); extern struct dlpResponse *dlp_response_new PI_ARGS((enum dlpFunctions cmd, int argc)); extern ssize_t dlp_response_read PI_ARGS((struct dlpResponse **res, int sd)); extern ssize_t dlp_request_write PI_ARGS((struct dlpRequest *req, int sd)); extern void dlp_response_free PI_ARGS((struct dlpResponse *req)); extern int dlp_exec PI_ARGS((int sd, struct dlpRequest *req, struct dlpResponse **res)); extern char *dlp_errorlist[]; extern char *dlp_strerror(int error); struct RPC_params; extern int dlp_RPC PI_ARGS((int sd, struct RPC_params * p, unsigned long *result)); #endif /* !SWIG */ /*@}*/ /** @name DLP library functions */ /*@{*/ /** @brief Set the version of the DLP protocol we report to the device. * * During the handshake phase, the device and the desktop exchange the * version of the DLP protocol both support. If the device's DLP version * is higher than the desktop's, the device usually refuses to connect. * * @note Call this function prior to accepting or initiating a connection. * * @param major Protocol major version * @param minor Protocol minor version */ extern void dlp_set_protocol_version PI_ARGS((int major, int minor)); /** @brief Convert a Palm OS date to a local date * * Local dates are using the local machine's timezone. If the Palm OS date * is undefined, the local date is set to @c 0x83DAC000 (Fri Jan 1 00:00:00 1904 GMT) * * @param timeDateData Ptr to a time/date data block returned by Palm OS * @return converted date */ extern time_t dlp_ptohdate PI_ARGS((PI_CONST unsigned char *timeDateData)); /** @brief Convert a date to Palm OS date * * If the local date is @c 0x83DAC000 (Fri Jan 1 00:00:00 1904 GMT) the Palm OS date * is set to undefined. Otherwise the date is converted from local time to Palm OS * * @param palm_time The date to convert * @param timeDateData Ptr to an 8 byte buffer to hold the Palm OS date */ extern void dlp_htopdate PI_ARGS((time_t palm_time, unsigned char *timeDateData)); /*@}*/ /** @name System functions */ /*@{*/ /** @brief Get the time from the device and return it as a local time_t value * * @param sd Socket number * @param palm_time Pointer to a time_t to fill * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_GetSysDateTime PI_ARGS((int sd, time_t *palm_time)); /** @brief Set the time on the Palm using a local time_t value. * * @param sd Socket number * @param palm_time New time to set the device to (expressed using the computer's timezone) * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_SetSysDateTime PI_ARGS((int sd, time_t palm_time)); /** @brief Read the system information block * * @param sd Socket number * @param sysinfo Returned system information * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadSysInfo PI_ARGS((int sd, struct SysInfo *sysinfo)); /** @brief Read information about internal handheld memory * * @param sd Socket number * @param cardno Card number (zero based) * @param cardinfo Returned information about the memory card. * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadStorageInfo PI_ARGS((int sd, int cardno, struct CardInfo *cardinfo)); /** @brief Read the device user information * * @param sd Socket number * @param user Returned user info * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadUserInfo PI_ARGS((int sd, struct PilotUser *user)); /** @brief Change the device user information * * @param sd Socket number * @param INPUT New user info * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_WriteUserInfo PI_ARGS((int sd, PI_CONST struct PilotUser *INPUT)); /** @brief Convenience function to reset lastSyncPC in the UserInfo to 0 * * @param sd Socket number * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ResetLastSyncPC PI_ARGS((int sd)); /** @brief Read Network HotSync information * * Supported on Palm OS 2.0 and later. * * @param sd Socket number * @param OUTPUT On return, filled NetSyncInfo structure * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadNetSyncInfo PI_ARGS((int sd, struct NetSyncInfo *OUTPUT)); /** @brief Set Network HotSync information * * Supported on Palm OS 2.0 and later * * @param sd Socket number * @param INPUT NetSyncInfo structure to set * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_WriteNetSyncInfo PI_ARGS((int sd, PI_CONST struct NetSyncInfo *INPUT)); /** @brief State that a conduit has started running on the desktop * * Puts up a status message on the device. Calling this method regularly * is also the only reliable way to know whether the user pressed the Cancel * button on the device. * * @param sd Socket number * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_OpenConduit PI_ARGS((int sd)); /** @brief Terminate connection with the device * * Required at the end of a session. The pi_socket layer * will call this for you if you don't. After the device receives this * command, it will terminate the connection. * * @param sd Socket number * @param status End of sync status (see #dlpEndStatus enum) * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_EndOfSync PI_ARGS((int sd, int status)); /** @brief Terminate HotSync _without_ notifying Palm. * * This will cause the Palm to time out, and should (if I remember right) * lose any changes to unclosed databases. _Never_ use under ordinary * circumstances. If the sync needs to be aborted in a reasonable * manner, use EndOfSync with a non-zero status. * * @param sd Socket number * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_AbortSync PI_ARGS((int sd)); /** @brief Read a Feature from the device * * @param sd Socket number * @param creator Feature creator * @param num Feature number * @param feature On return, the feature value * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadFeature PI_ARGS((int sd, unsigned long creator, int num, unsigned long *feature)); /** @brief Emulation of the SysGetROMToken function on the device * * Supported on Palm OS 2.0 through 4.0. Using this function * is not recommended. * * @warning This function uses 68K RPC calls to perform its duty, * and is therefore not supported on devices running Palm OS 5.0 * and later. Actually, it may even crash the device. * * @param sd Socket number * @param token ROM token to read * @param databuf Buffer to store the token data in * @param datasize Size of data to read * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_GetROMToken PI_ARGS((int sd, unsigned long token, void *databuf, size_t *datasize)); /** @brief Add an entry into the HotSync log on the device * * Move to the next line with \\n, as usual. You may invoke this * command once or more before calling dlp_EndOfSync(), but it is * not required. * * @param sd Socket number * @param string Nul-terminated string with the text to insert in the log * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_AddSyncLogEntry PI_ARGS((int sd, char *string)); /** @brief Call an application on the device * * 32-bit retcode and data over 64k only supported on Palm OS 2.0 and later. * * This function allows calling an application (or any PRC that responds * to launch codes) using a custom launch code and custom data. The * application can return data too, using DlkControl() and the * dlkCtlSendCallAppReply selector. See Palm OS documentation for more * information. * * @param sd Socket number * @param creator Creator code of the application to call * @param type Type code of the application to call * @param action Launch code to send to the application * @param datasize Length of data block to pass to the application * @param databuf Data block to pass to the application * @param retcode On return, result code returned by the application * @param retbuf Buffer allocated using pi_buffer_new(). On return contains the data returned by the application * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_CallApplication PI_ARGS((int sd, unsigned long creator, unsigned long type, int action, size_t datasize, PI_CONST void *databuf, unsigned long *retcode, pi_buffer_t *retbuf)); /** @brief Convenience function to ead an app preference data block * * Supported on Palm OS 2.0 and later, emulated for Palm OS 1.x. * * @param sd Socket number * @param creator Application creator * @param prefid Preference ID * @param backup If set, read from backup prefs (see Palm OS documentation). This flag is ignored on Palm OS 1.x. * @param maxsize Maximum size of the data to return in buffer * @param databuf If not NULL, buffer should be of size @p maxsize. On return, contains the preference data * @param datasize If not NULL, on return contains the size of the preference data block * @param version If not NULL * @return A negative value if an error occured (see pi-error.h), otherwise the size of the preference block */ extern PI_ERR dlp_ReadAppPreference PI_ARGS((int sd, unsigned long creator, int prefid, int backup, int maxsize, void *databuf, size_t *datasize, int *version)); /** @brief Write an app preference data block * * Supported on Palm OS 2.0 and later. Emulated on Palm OS 1.x. * * @param sd Socket number * @param creator Application creator * @param prefid Preference ID * @param backup If set, write to backup prefs (see Palm OS documentation). This flag is ignored on Palm OS 1.x. * @param version Version of the pref to write * @param databuf Ptr to the data to write * @param datasize Size of the data to write * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_WriteAppPreference PI_ARGS((int sd, unsigned long creator, int prefid, int backup, int version, PI_CONST void *databuf, size_t datasize)); /** @brief Require reboot of device after HotSync terminates * * @param sd Socket number * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ResetSystem PI_ARGS((int sd)); /*@}*/ /** @name Database access functions */ /*@{*/ /** @brief Read the database list from the device * * The database list can be read either one database at a time (slower), * or passing ::dlpDBListMultiple in the @p flags member. Pass ::dlpDBListRAM * in @p flags to get the list of databases in RAM, and ::dlpDBListROM to get * the list of databases in ROM. You can mix flags to obtain the desired * result. Passing ::dlpDBListMultiple will return several DBInfo * structures at once (usually 20). Use (info->used / sizeof(DBInfo)) to * know how many database information blocks were returned. * For the next call, pass the last DBInfo->index value + 1 to start to * the next database. @n @n * When all the database informations have been retrieved, this function returns * #PI_ERR_DLP_PALMOS and pi_palmos_error() returns #dlpErrNotFound. * * @param sd Socket number * @param cardno Card number (should be 0) * @param flags Flags (see #dlpDBList enum) * @param start Index of first database to list (zero based) * @param dblist Buffer filled with one or more DBInfo structure * @return A negative value if an error occured or the DB list is exhausted (see pi-error.h) * */ extern PI_ERR dlp_ReadDBList PI_ARGS((int sd, int cardno, int flags, int start, pi_buffer_t *dblist)); /** @brief Find a database by name * * Supported on Palm OS 3.0 (DLP 1.2) and later. * * @param sd Socket number * @param cardno Memory card number (usually 0) * @param dbname Database name * @param localid If not NULL, on return contains the LocalID of the database if it was found * @param dbhandle If not NULL, on return contains the handle of the database if it is currently open * @param dbInfo If not NULL, on return contains information about the database * @param dbSize If not NULL, on return contains information about the database size * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_FindDBByName PI_ARGS((int sd, int cardno, PI_CONST char *dbname, unsigned long *localid, int *dbhandle, struct DBInfo *dbInfo, struct DBSizeInfo *dbSize)); /** @brief Get information about an open database * * Supported on Palm OS 3.0 (DLP 1.2) and later. * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param cardno If not NULL, on return contains the cardno of the memory card the database resides on * @param localid If not NULL, on return contains the LocalID of the database * @param dbInfo If not NULL, on return contains information about the database * @param dbSize If not NULL, on return contains information about the database size * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_FindDBByOpenHandle PI_ARGS((int sd, int dbhandle, int *cardno, unsigned long *localid, struct DBInfo *dbInfo, struct DBSizeInfo *dbSize)); /** @brief Find databases by type and/or creator * * Supported on Palm OS 3.0 (DLP 1.2) and later. To look for multiple databases, * make a first call with @p start set to 1, then subsequent calls with @p start set to 0 * until no more database is found. * * @param sd Socket number * @param type If not 0, type code to look for * @param creator If not 0, creator code to look for * @param start If set, start a new search * @param latest If set, returns the database with the latest version if there are several identical databases * @param cardno If not NULL, on return contains the memory card number the database resides on * @param localid If not NULL, on return contains the LocalID of the database * @param dbhandle If not NULL, on return contains the handle of the database if it is currently open * @param dbInfo If not NULL, on return contains information about the database * @param dbSize If not NULL, on return contains information about the database size * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_FindDBByTypeCreator PI_ARGS((int sd, unsigned long type, unsigned long creator, int start, int latest, int *cardno, unsigned long *localid, int *dbhandle, struct DBInfo *dbInfo, struct DBSizeInfo *dbSize)); /** @brief Look for a database on the device * * This function does not match any DLP layer function, but is * intended as a shortcut for programs looking for databases. It * uses a fairly byzantine mechanism for ordering the RAM databases * before the ROM ones. You must feed the @a index slot from the * returned info in @p start the next time round. * * @param sd Socket number * @param cardno Card number (should be 0) * @param start Index of first database to list (zero based) * @param dbname If not NULL, look for a database with this name * @param type If not 0, matching database must have this type * @param creator If not 0, matching database must have this creator code * @param OUTPUT Returned database information on success * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_FindDBInfo PI_ARGS((int sd, int cardno, int start, PI_CONST char *dbname, unsigned long type, unsigned long creator, struct DBInfo *OUTPUT)); /** @brief Open a database on the Palm. * * @param sd Socket number * @param cardno Card number (should be 0) * @param mode Open mode (see #dlpOpenFlags enum) * @param dbname Database name * @param dbhandle Returned database handle to use if other calls like dlp_CloseDB() * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_OpenDB PI_ARGS((int sd, int cardno, int mode, PI_CONST char *dbname, int *dbhandle)); /** @brief Close an opened database * * @param sd Socket number * @param dbhandle The DB handle returned by dlp_OpenDB() * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_CloseDB PI_ARGS((int sd, int dbhandle)); /** @brief Close all opened databases * * @param sd Socket number * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_CloseDB_All PI_ARGS((int sd)); /** @brief Delete an existing database from the device * * @param sd Socket number * @param cardno Card number (should be 0) * @param dbname Database name * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_DeleteDB PI_ARGS((int sd, int cardno, PI_CONST char *dbname)); /** @brief Create database on the device * * After creation, the database is open and ready for use. You should * call dlp_CloseDB() once you're done with the database. * * @param sd Socket number * @param creator Creator code for the new database (four-char code) * @param type Type code for the new database (four-char code) * @param cardno Card number (should be 0) * @param flags Database flags (see #dlpDBFlags enum) * @param version Database version number * @param dbname Database name * @param dbhandle On return, DB handle to pass to other calls like dlp_CloseDB() * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_CreateDB PI_ARGS((int sd, unsigned long creator, unsigned long type, int cardno, int flags, unsigned int version, PI_CONST char *dbname, int *dbhandle)); /** @brief Return the number of records in an opened database. * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param numrecs On return, number of records in the database * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadOpenDBInfo PI_ARGS((int sd, int dbhandle, int *numrecs)); /** @brief Change information for an open database * * Supported on Palm OS 3.0 (DLP 1.2) and later. * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param flags Flags to set for this database (see #dlpDBFlags enum) * @param clearFlags Flags to clear for this database (see #dlpDBFlags enum) * @param version Version of this database * @param createDate Creation date of this database * @param modifyDate Modification date of this database (use @c 0x83DAC000 to unset) * @param backupDate Last backup date of this database (use @c 0x83DAC000 to unset) * @param type Database type code (four-char code) * @param creator Database creator code (four-char code) * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_SetDBInfo PI_ARGS((int sd, int dbhandle, int flags, int clearFlags, unsigned int version, time_t createDate, time_t modifyDate, time_t backupDate, unsigned long type, unsigned long creator)); /** @brief Delete a category from a database * * Any record in that category will be moved to the Unfiled category. * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param category Category to delete * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_DeleteCategory PI_ARGS((int sd, int dbhandle, int category)); /** @brief Move all records from a category to another category * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param fromcat Category to move from (0-15) * @param tocat Category to move to (0-15) * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_MoveCategory PI_ARGS((int sd, int dbhandle, int fromcat, int tocat)); /** @brief Read a database's AppInfo block * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param offset Offset to start reading from (0 based) * @param reqbytes Number of bytes to read (pass -1 to read all data from @p offset to the end of the AppInfo block) * @param retbuf Buffer allocated using pi_buffer_new(). On return contains the data from the AppInfo block * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadAppBlock PI_ARGS((int sd, int dbhandle, int offset, int reqbytes, pi_buffer_t *retbuf)); /** @brief Write a database's AppInfo block * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param databuf Pointer to the new AppInfo data. * @param datasize Length of the new AppInfo data. If 0, the AppInfo block is removed. * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_WriteAppBlock PI_ARGS((int sd, int dbhandle, PI_CONST void *databuf, size_t datasize)); /** @brief Read a database's SortInfo block * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param offset Offset to start reading from (0 based) * @param reqbytes Number of bytes to read (pass -1 to read all data from @p offset to the end of the SortInfo block) * @param retbuf Buffer allocated using pi_buffer_new(). On return contains the data from the SortInfo block * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadSortBlock PI_ARGS((int sd, int dbhandle, int offset, int reqbytes, pi_buffer_t *retbuf)); /** @brief Write a database's SortInfo block * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param databuf Pointer to the new SortInfo data. * @param datasize Length of the new SortInfo data. If 0, the SortInfo block is removed. * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_WriteSortBlock PI_ARGS((int sd, int dbhandle, PI_CONST void *databuf, size_t datasize)); /** @brief Clean up a database by removing deleted/archived records * * Delete all records in the opened database which are marked as * archived or deleted. * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_CleanUpDatabase PI_ARGS((int sd, int dbhandle)); /** @brief Reset dirty record flags, update sync time * * For record databases, reset all dirty flags. For both record and * resource databases, set the last sync time to now. * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ResetSyncFlags PI_ARGS((int sd, int dbhandle)); /** @brief Reset the nextRecord position used in dlp_ReadNextRecInCategory() * * This resets the nextRecord both internally and on the device. * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ResetDBIndex PI_ARGS((int sd, int dbhandle)); /** @brief Read the list of record IDs from an open database * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param sort If non-zero, the on-device application with the same DB creator will be called to re-sort the records prior to returning the list * @param start Index of first record ID to return (zero based) * @param max Maximum number of record IDs to return * @param recuids On return, @p count record UIDs * @param count On return, the number of record IDs found in @p IDs * @return A negative value if an error occured (see pi-error.h) */ #ifndef SWIG /* bindings provide a native implementation */ extern PI_ERR dlp_ReadRecordIDList PI_ARGS((int sd, int dbhandle, int sort, int start, int max, recordid_t *recuids, int *count)); #endif /** @brief Read a record using its unique ID * * Read a record identified by its unique ID. Make sure you only * request records that effectively exist in the database (use * dlp_ReadRecordIDList() to retrieve the unique IDs of all records * in the database). * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param recuid Record unique ID * @param retbuf If not NULL, a buffer allocated using pi_buffer_new(). On return, contains the record contents * @param recindex If not NULL, contains the record index on return. * @param recattrs If not NULL, contains the record attributes on return. * @param category If not NULL, contains the record category on return. * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadRecordById PI_ARGS((int sd, int dbhandle, recordid_t recuid, pi_buffer_t *retbuf, int *recindex, int *recattrs, int *category)); /** @brief Read a record using its index * * Read a record by record index (zero-based). Make sure you only * request records within the bounds of database records * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param recindex Record index (zero based) * @param retbuf If not NULL, a buffer allocated using pi_buffer_new(). On return, contains the record contents * @param recuid If not NULL, contains the record UID on return. * @param recattrs If not NULL, contains the record attributes on return. * @param category If not NULL, contains the record category on return. * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadRecordByIndex PI_ARGS((int sd, int dbhandle, int recindex, pi_buffer_t *retbuf, recordid_t *recuid, int *recattrs, int *category)); /** @brief Iterate through modified records in database * * Return subsequent modified records on each call. Use dlp_ResetDBIndex() * prior to starting iterations. Once all the records have been seen, * this function returns PI_ERR_DLP_PALMOS and pi_palmos_error() returns * #dlpErrNotFound. * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param retbuf If not NULL, a buffer created using pi_buffer_new(). Buffer is cleared first using pi_buffer_clear(). On return, contains the record data * @param recuid If not NULL, contains the record unique ID on return * @param recindex If not NULL, contains the record index on return * @param recattrs If not NULL, contains the record attributes on return (see #dlpRecAttributes enum) * @param category If not NULL, contains the record category on return * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadNextModifiedRec PI_ARGS((int sd, int dbhandle, pi_buffer_t *retbuf, recordid_t *recuid, int *recindex, int *recattrs, int *category)); /** @brief Iterate through modified records in category * * Return subsequent modified records on each call. Use dlp_ResetDBIndex() * prior to starting iterations. Once all the records have been seen, * this function returns PI_ERR_DLP_PALMOS and pi_palmos_error() returns * #dlpErrNotFound. * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param category The category to iterate into * @param retbuf If not NULL, a buffer created using pi_buffer_new(). Buffer is cleared first using pi_buffer_clear(). On return, contains the record data * @param recuid If not NULL, contains the record unique ID on return * @param recindex If not NULL, contains the record index on return * @param recattrs If not NULL, contains the record attributes on return (see #dlpRecAttributes enum) * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadNextModifiedRecInCategory PI_ARGS((int sd, int dbhandle, int category, pi_buffer_t *retbuf, recordid_t *recuid, int *recindex, int *recattrs)); /** @brief Iterate through records in category * * Return subsequent records on each call. Use dlp_ResetDBIndex() * prior to starting iterations. Once all the records have been seen, * this function returns PI_ERR_DLP_PALMOS and pi_palmos_error() returns * #dlpErrNotFound. * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param category The category to iterate into * @param retbuf If not NULL, a buffer created using pi_buffer_new(). Buffer is cleared first using pi_buffer_clear(). On return, contains the record data * @param recuid If not NULL, contains the record unique ID on return * @param recindex If not NULL, contains the record index on return * @param recattrs If not NULL, contains the record attributes on return (see #dlpRecAttributes enum) * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadNextRecInCategory PI_ARGS((int sd, int dbhandle, int category, pi_buffer_t *retbuf, recordid_t *recuid, int *recindex, int *recattrs)); /** @brief Create a new record in a database * * Use this call to add records to a database. On DLP 1.4 and later, you can create records * bigger than 64k. Set the record ID to 0 to have the device generate the record ID itself, * or assign a record ID of your own. Read Palm's documentation for information about * record IDs, as there is a way to indicate which records were created by the desktop and * which ones were created by the device applications. * * If you pass -1 as the data length, the function will treat the data as a string and use * strlen(data)+1 as the data length (that is, the string is written including the * terminating nul character). * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param flags Record attributes (see #dlpRecAttributes enum) * @param recuid Record ID of the new record. If 0, device will generate a new record ID for this record. * @param catid Category of the new record * @param databuf Ptr to record data * @param datasize Record data length * @param newrecuid On return, record ID that was assigned to this record * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_WriteRecord PI_ARGS((int sd, int dbhandle, int flags, recordid_t recuid, int catid, PI_CONST void *databuf, size_t datasize, recordid_t *newrecuid)); /** @brief Delete an existing record from a database * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param all If set, ALL records are deleted from the database. * @param recuid Record ID of record to delete if @p all == 0. * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_DeleteRecord PI_ARGS((int sd, int dbhandle, int all, recordid_t recuid)); /** @brief Read a resource identified by its type and ID * * @note To read resources larger than 64K, you should use dlp_ReadResourceByIndex(). * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param type Type code for the resource (four-char code) * @param resid Resource ID * @param retbuf If not NULL, a buffer allocated using pi_buffer_new(). On return, contains the resource contents * @param resindex If not NULL, on return contains the resource index * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadResourceByType PI_ARGS((int sd, int dbhandle, unsigned long type, int resid, pi_buffer_t *retbuf, int *resindex)); /** @brief Read a resource identified by its resource index * * This function supports reading resources larger than 64k on * DLP 1.4 and later (Palm OS 5.2 and later). * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param resindex Resource index * @param retbuf If not NULL, a buffer allocated using pi_buffer_new(). On return, contains the resource contents * @param restype If not NULL, on return contains the resource type * @param resid If not NULL, on return contains the resource ID * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ReadResourceByIndex PI_ARGS((int sd, int dbhandle, unsigned int resindex, pi_buffer_t *retbuf, unsigned long *restype, int *resid)); /** @brief Create a new resource of overwrite an existing one * * This function supports writing resources larger than 64k on * DLP 1.4 and later (Palm OS 5.2 and later). * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param restype Resource type (four-char code) * @param resid Resource ID * @param databuf Ptr to resource data * @param datasize Length of resource data to write * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_WriteResource PI_ARGS((int sd, int dbhandle, unsigned long restype, int resid, PI_CONST void *databuf, size_t datasize)); /** @brief Delete a resource or all resources from a resource file * * @param sd Socket number * @param dbhandle Open database handle, obtained from dlp_OpenDB() * @param all If set, all resources are removed from this database (@p restype and @p resid are ignored) * @param restype Resource type (four-char code) * @param resid Resource ID * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_DeleteResource PI_ARGS((int sd, int dbhandle, int all, unsigned long restype, int resid)); /*@}*/ /** @name Expansion manager functions */ /*@{*/ /** @brief Enumerate expansion slots * * Supported on Palm OS 4.0 and later. Expansion slots are physical slots * present on the device. To check whether a card is inserted in a slot, * use dlp_ExpCardPresent(). * * @param sd Socket number * @param numslots On input, maximum number of slots that can be returned in the slotRefs array. On return, the actual number of slot references returned in @p slotRefs. * @param slotrefs On return, @p numSlots slot references * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ExpSlotEnumerate PI_ARGS((int sd, int *numslots, int *slotrefs)); /** @brief Checks whether a card is inserted in a slot * * Supported on Palm OS 4.0 and later. Returns >=0 if a card * is inserted in the slot. * * @param sd Socket number * @param slotref The slot reference as returned by dlp_ExpSlotEnumerate(). * @return A negative value if an error occured (see pi-error.h), >=0 if a card is inserted */ extern PI_ERR dlp_ExpCardPresent PI_ARGS((int sd, int slotref)); /** @brief Get information about a removable card inserted in an expansion slot * * Supported on Palm OS 4.0 and later. The info strings are returned in a * single malloc()'ed buffer as a suite of nul-terminated string, one * after the other. * * @param sd Socket number * @param slotref The slot reference as returned by dlp_ExpSlotEnumerate(). * @param expflags If not NULL, the card flags (see #dlpExpCardCapabilities enum) * @param numstrings On return, the number of strings found in the @p strings array * @param strings If not NULL, ptr to a char*. If there are strings to return, this function allocates a buffer to hold the strings. You are responsible for free()'ing the buffer once you're done with it. * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ExpCardInfo PI_ARGS((int sd, int slotref, unsigned long *expflags, int *numstrings, char **strings)); /** @brief Return the type of media supported by an expansion slot * * Supported on Palm OS 5.2 and later (DLP 1.4 and later). * * @param sd Socket number * @param slotref The slot reference as returned by dlp_ExpSlotEnumerate(). * @param mediatype On return, the media type * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_ExpSlotMediaType PI_ARGS((int sd, int slotref, unsigned long *mediatype)); /*@}*/ /** @name VFS manager functions */ /*@{*/ /** @brief Returns a list of connected VFS volumes * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param numvols On input, the maximum number of volume references that can be returned. On output, the actual number of volume references * @param volrefs On output, @p numVols volume references * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSVolumeEnumerate PI_ARGS((int sd, int *numvols, int *volrefs)); /** @brief Returns information about a VFS volume * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param volinfo On return, volume information * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSVolumeInfo PI_ARGS((int sd, int volref, struct VFSInfo *volinfo)); /** @brief Return the label (name) of a VFS volume * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param len On input, the maximum size of the name buffer. On output, the name length (including the ending nul byte) * @param name On output, the nul-terminated volume name * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSVolumeGetLabel PI_ARGS((int sd, int volref, int *len, char *name)); /** @brief Change the label (name) of a VFS volume * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param name New volume name * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSVolumeSetLabel PI_ARGS((int sd, int volref, PI_CONST char *name)); /** @brief Return the total and used size of a VFS volume * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param usedbytes On return, number of bytes used on the volume * @param totalbytes On return, total size of the volume in bytes * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSVolumeSize PI_ARGS((int sd, int volref, long *usedbytes, long *totalbytes)); /** @brief Format a VFS volume * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fmtflags Format flags (undocumented for now) * @param fsLibRef File system lib ref (undocumented for now) * @param param Slot mount parameters (undocumented for now) * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSVolumeFormat PI_ARGS((int sd, unsigned char fmtflags, int fsLibRef, struct VFSSlotMountParam *param)); /** @brief Get the default storage directory for a given file type * * Supported on Palm OS 4.0 and later. Return the default directory * for a file type. File types as expressed as MIME types, for * example "image/jpeg", or as a simple file extension (i.e. ".jpg") * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param name MIME type to get the default directory for * @param dir A buffer to hold the default path * @param len On input, the length of the @p dir buffer. On return, contains the length of the path string (including the nul terminator) * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSGetDefaultDir PI_ARGS((int sd, int volref, PI_CONST char *name, char *dir, int *len)); /** @brief Iterate through the entries in a directory * * Supported on Palm OS 4.0 and later. At the beginning you set * @p dirIterator to #vfsIteratorStart, then call this function * repeatedly until it returns an error code of the iterator becomes * #vfsIteratorStop. * * @bug On some early OS 5 devices like Tungsten T and Sony NX70, NX73 this * call crashes the device. This has been confirmed to be a bug in HotSync on * the device, as tests showed that a regular HotSync conduit does crash the * device with this call too. * * @param sd Socket number * @param dirref Directory reference obtained from dlp_VFSFileOpen() * @param diriterator Ptr to an iterator. Start with #vfsIteratorStart * @param maxitems On input, the max number of VFSDirInfo structures stored in @p dirItems. On output, the actual number of items. * @param diritems Preallocated array that contains a number of VFSDirInfo structures on return. * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSDirEntryEnumerate PI_ARGS((int sd, FileRef dirref, unsigned long *diriterator, int *maxitems, struct VFSDirInfo *diritems)); /** @brief Create a new directory on a VFS volume * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param path Full path for the directory to create * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSDirCreate PI_ARGS((int sd, int volref, PI_CONST char *path)); /** @brief Import a VFS file to a database on the handheld * * Supported on Palm OS 4.0 and later. The file is converted to a * full fledged database and stored in the handheld's RAM. * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param pathname Path of the file to transfer to the handheld * @param cardno On return, card number the database was created on (usually 0) * @param localid On return, LocalID of the database that was created * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSImportDatabaseFromFile PI_ARGS((int sd, int volref, PI_CONST char *pathname, int *cardno, unsigned long *localid)); /** @brief Export a database to a VFS file * * Supported on Palm OS 4.0 and later. The database is converted to a * .prc, .pdb or .pqa file on the VFS volume. * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param pathname Path of the file to create on the VFS volume * @param cardno Card number the database resides on (usually 0) * @param localid LocalID of the database to export * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSExportDatabaseToFile PI_ARGS((int sd, int volref, PI_CONST char *pathname, int cardno, unsigned int localid)); /** @brief Create a new file on a VFS volume * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param pathname Full path of the file to create * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSFileCreate PI_ARGS((int sd, int volref, PI_CONST char *pathname)); /** @brief Open an existing file on a VFS volume * * Supported on Palm OS 4.0 and later. On some devices, it is required to open the * file using the #dlpOpenReadWrite mode to be able to write to it (using * #dlpOpenWrite is not enough). * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param path Full path of the file to open * @param mode Open mode flags (see #dlpVFSOpenFlags enum) * @param fileref On return, file reference to the open file * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSFileOpen PI_ARGS((int sd, int volref, PI_CONST char *path, int mode, FileRef *fileref)); /** @brief Close an open VFS file * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fileref File reference obtained from dlp_VFSFileOpen() * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSFileClose PI_ARGS((int sd, FileRef fileref)); /** @brief Write data to an open file * * Supported on Palm OS 4.0 and later. Will return the number of bytes * written if successful. * * @param sd Socket number * @param fileref File reference obtained from dlp_VFSFileOpen() * @param databuf Ptr to the data to write * @param datasize Length of the data to write * @return A negative value if an error occured (see pi-error.h), the number of bytes written otherwise. */ extern PI_ERR dlp_VFSFileWrite PI_ARGS((int sd, FileRef fileref, PI_CONST void *databuf, size_t datasize)); /** @brief Read data from an open file * * Supported on Palm OS 4.0 and later. Will return the total number of bytes * actually read. * * @param sd Socket number * @param fileref File reference obtained from dlp_VFSFileOpen() * @param retbuf Buffer allocated using pi_buffer_new(). Buffer is being emptied first with pi_buffer_clear(). On return contains the data read from the file. * @param reqbytes Number of bytes to read from the file. * @return A negative value if an error occured (see pi-error.h), or the total number of bytes read */ extern PI_ERR dlp_VFSFileRead PI_ARGS((int sd, FileRef fileref, pi_buffer_t *retbuf, size_t reqbytes)); /** @brief Delete an existing file from a VFS volume * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param pathname Full access path to the file to delete * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSFileDelete PI_ARGS((int sd, int volref, PI_CONST char *pathname)); /** @brief Rename an existing file * * Supported on Palm OS 4.0 and later. * * @note This function can NOT be used to move a file from one place * to another. You can only rename a file that will stay in the same * directory. * * @param sd Socket number * @param volref Volume reference number (obtained from dlp_VFSVolumeEnumerate()) * @param pathname Full access path to the file to rename * @param newname New file name, without the rest of the access path * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSFileRename PI_ARGS((int sd, int volref, PI_CONST char *pathname, PI_CONST char *newname)); /** @brief Checks whether the current position is at the end of file * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fileref File reference obtained from dlp_VFSFileOpen() * @return A negative value if an error occured (see pi-error.h). 0 if not at EOF, >0 if at EOF. */ extern PI_ERR dlp_VFSFileEOF PI_ARGS((int sd, FileRef fileref)); /** @brief Return the current seek position in an open file * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fileref File reference obtained from dlp_VFSFileOpen() * @param position On return, current absolute position in the file * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSFileTell PI_ARGS((int sd, FileRef fileref, int *position)); /** @brief Return the attributes of an open file * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fileref File reference obtained from dlp_VFSFileOpen() * @param fileattrs On return, file attributes (see #dlpVFSFileAttributeConstants enum) * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSFileGetAttributes PI_ARGS((int sd, FileRef fileref, unsigned long *fileattrs)); /** @brief Change the attributes of an open file * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fileref File reference obtained from dlp_VFSFileOpen() * @param fileattrs n-New file attributes (see #dlpVFSFileAttributeConstants enum) * @return A negative value if an error occured (see pi-error.h). */ extern PI_ERR dlp_VFSFileSetAttributes PI_ARGS((int sd, FileRef fileref, unsigned long fileattrs)); /** @brief Return one of the dates associated with an open file or directory * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fileref File or directory reference obtained from dlp_VFSFileOpen() * @param which The date you want (see #dlpVFSDateConstants enum) * @param date On return, the requested date * @return A negative value if an error occured (see pi-error.h). */ extern PI_ERR dlp_VFSFileGetDate PI_ARGS((int sd, FileRef fileref, int which, time_t *date)); /** @brief Change one of the dates for an open file or directory * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fileref File or directory reference obtained from dlp_VFSFileOpen() * @param which The date you want to change (see #dlpVFSDateConstants enum) * @param date The new date to set * @return A negative value if an error occured (see pi-error.h). */ extern PI_ERR dlp_VFSFileSetDate PI_ARGS((int sd, FileRef fileref, int which, time_t date)); /** @brief Change the current seek position in an open file * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fileref File or directory reference obtained from dlp_VFSFileOpen() * @param origin Where to seek from (see #dlpVFSSeekConstants enum) * @param offset Seek offset * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSFileSeek PI_ARGS((int sd, FileRef fileref, int origin, int offset)); /** @brief Resize an open file * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fileref File or directory reference obtained from dlp_VFSFileOpen() * @param newsize New file size * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSFileResize PI_ARGS((int sd, FileRef fileref, int newsize)); /** @brief Return the size of an open file * * Supported on Palm OS 4.0 and later. * * @param sd Socket number * @param fileref File or directory reference obtained from dlp_VFSFileOpen() * @param size On return, the actual size of the file * @return A negative value if an error occured (see pi-error.h) */ extern PI_ERR dlp_VFSFileSize PI_ARGS((int sd, FileRef fileref, int *size)); /*@}*/ #ifdef __cplusplus } #endif #endif /*_PILOT_DLP_H_*/