/*
 * $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 <unistd.h>

#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_*/
