1 files changed, 435 insertions, 0 deletions
diff --git a/debian/pilot-link/pilot-link-0.12.5-dfsg/include/pi-file.h b/debian/pilot-link/pilot-link-0.12.5-dfsg/include/pi-file.h
new file mode 100644
index 00000000..530997de
--- /dev/null
+++ b/debian/pilot-link/pilot-link-0.12.5-dfsg/include/pi-file.h
@@ -0,0 +1,435 @@
+/*
+ * $Id: pi-file.h,v 1.29 2006/10/17 13:24:07 desrod Exp $
+ *
+ * pi-file.h: Pilot File Interface Library
+ *
+ * This is free software, licensed under the GNU Library Public License V2.
+ * See the file COPYING.LIB for details.
+ *
+ * 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-file.h
+ *  @brief Database file install, retrieve and management interface
+ *
+ * The pi-file layer is a convenience management library that provides for
+ * easy access, creation, install and retrieve of database files (PRC, PDB,
+ * PQA)
+ *
+ * Palm databases on the local machines can be created with pi_file_create()
+ * or opened read-only using pi_file_open(). Several functions are provided
+ * to access resources and records. Caller must make sure to use the
+ * appropriate functions, depending on the type of the database (i.e. only
+ * use the record read/write functions on data databases, only use the
+ * resource read/write functions on resource databases).
+ *
+ * A set of utility functions are provided to facilitate installing and
+ * retrieving databases on the devide. pi_file_install() will perform all
+ * the steps required to install a database on a device. pi_file_merge() can
+ * be used to update an existing database or add new records/resources to
+ * it.  pi_file_retrieve() will read a database from the device.
+ */
+
+#ifndef _PILOT_FILE_H_
+#define _PILOT_FILE_H_
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "pi-dlp.h"		/* For DBInfo */
+
+/** @brief Structure describing a record or resource entry in a database file */
+typedef struct pi_file_entry {
+	int 	offset;			/**< Offset in the on-disk file */
+	int	size;			/**< Size of the resource or record */
+	int	resource_id;		/**< For resources, resource ID */
+	int	attrs;			/**< Record attributes */
+	unsigned long type;		/**< For resdources, resource type */
+	recordid_t uid;			/**< For records, record unique ID */
+} pi_file_entry_t;
+
+typedef struct pi_file {
+	int 	err;
+	int	for_writing;		/**< Non-zero if the file was opened with pi_file_create() */
+	int	app_info_size;		/**< Size of the appInfo block */
+	int	sort_info_size;		/**< Size of the sortInfo block */
+	int	next_record_list_id;
+	int	resource_flag;
+	int	ent_hdr_size;		/**< Size of the header for each resource/record (depends on whether the file is a resource or record file) */
+	int	num_entries;		/**< Number of actual entries in the entries memory block */
+	int	num_entries_allocated;	/**< Number of entries allocated in the entries memory block */
+	int	rbuf_size;		/**< Size of the internal read buffer */
+	FILE 	*f;			/**< Actual on-disk file */
+	pi_buffer_t *tmpbuf;		/**< Temporary buffer for databases opened with pi_file_create() */
+	char 	*file_name;		/**< Access path */
+	void 	*app_info;		/**< Pointer to the appInfo block or NULL */
+	void	*sort_info;		/**< Pointer to the sortInfo block or NULL */
+	void	*rbuf;			/**< Read buffer, used internally */
+	unsigned long unique_id_seed;	/**< Database file's unique ID seed as read from an existing file */
+	struct 	DBInfo info;		/**< Database information and attributes */
+	struct 	pi_file_entry *entries;	/**< Array of records / resources */
+} pi_file_t;
+
+/** @brief Transfer progress callback structure
+ *
+ * The progress callback structure is prepared by the client application and
+ * passed to pi_file_install(), pi_file_merge() and pi_file_retrieve()
+ * functions. It allows the client application to be notified during a file
+ * transfer (i.e. to update a progress indicator) and gives it a chance to
+ * cancel transfers.
+ */
+typedef struct {
+	int type;				/**< Transfer type (see #piProgressType enum) */
+	int transferred_bytes;			/**< Current transferred bytes */
+	void *userinfo;				/**< Provided by and passed back to client (not used for now, will be in a future release) */
+	union {
+		struct {
+			pi_file_t *pf;		/**< May be NULL */
+			struct DBSizeInfo size;	/**< Size information */
+			int transferred_records;/**< Number of records or resources */
+		} db;
+
+		struct {
+			char *path;		/**< VFS file path */
+			long total_bytes;	/**< File size in bytes */
+		} vfs;
+	} data;
+} pi_progress_t;
+
+/** @brief Progress callback function definition
+ *
+ * Callback should return either #PI_TRANSFER_STOP or
+ * #PI_TRANSFER_CONTINUE
+ */
+typedef int (*progress_func)(int socket, pi_progress_t *progress);
+
+/** @brief Transfer progress types for the @a type member of pi_progress_t */
+enum piProgressType {
+	PI_PROGRESS_SEND_DB = 1,		/**< Sending a database */
+	PI_PROGRESS_RECEIVE_DB,			/**< Receiving a database */
+	PI_PROGRESS_SEND_VFS,			/**< Sending a VFS file */
+	PI_PROGRESS_RECEIVE_VFS			/**< Receiving a VFS file */
+};
+
+
+#define PI_TRANSFER_STOP	0		/**< Returned by progress callback to stop the transfer */
+#define	PI_TRANSFER_CONTINUE	1		/**< Returned by progress callback to continue the transfer */
+
+/** @name Opening and closing files */
+/*@{*/
+	/** @brief Open a database for read-only access
+	 *
+	 * Don't dispose of the returned structure directly.
+	 * Use pi_file_close() instead.
+	 *
+	 * @param name The access path to the database to open on the local machine
+	 * @return An initialized pi_file_t structure or NULL.
+	 */
+	extern pi_file_t *pi_file_open
+		PI_ARGS((const char *name));
+
+	/** @brief Create a new database file
+	 *
+	 * A new database file is created on the local machine.
+	 *
+	 * @param name Access path of the new file to create
+	 * @param INPUT	Characteristics of the database to create
+	 * @return A new pi_file_t structure. Use pi_file_close() to write data and close file.
+	 */
+	extern pi_file_t *pi_file_create
+	    PI_ARGS((const char *name, const struct DBInfo *INPUT));
+
+	/** @brief Closes a local file
+	 *
+	 * If the file had been opened with pi_file_create, all
+	 * modifications are written to disk before the file is closed
+	 *
+	 * @param pf	The pi_file_t structure is being disposed of by this function
+	 * @return An error code (see file pi-error.h)
+	 */
+	extern int pi_file_close PI_ARGS((pi_file_t *pf));
+/*@}*/
+
+/** @name Reading from open files */
+/*@{*/
+	/** @brief Returns database specification
+	 *
+	 * @param pf	An open file
+	 * @return DBInfo structure describing the file
+	 */
+	extern void pi_file_get_info
+	    PI_ARGS((const pi_file_t *pf, struct DBInfo *OUTPUT));
+
+	/** @brief Returns the file's appInfo block
+	 *
+	 * The returned data is not a copy of the pi_file_t's appInfo
+	 * structures. Don't dispose or modify it.
+	 *
+	 * @param pf An open file
+	 * @param datap On return, ptr to appInfo data or NULL
+	 * @param sizep On return, size of the appInfoBlock
+	 */
+	extern void pi_file_get_app_info
+	    PI_ARGS((pi_file_t *pf, void **datap, size_t *sizep));
+
+	/** @brief Returns the file's sortInfo block
+	 *
+	 * The returned data is not a copy of the pi_file_t's sortInfo
+	 * block: do not dispose of it!
+	 *
+	 * @param pf An open file
+	 * @param datap On return, ptr to sortInfo data or NULL
+	 * @param sizep On return, size of the sortInfoBlock
+	 */
+	extern void pi_file_get_sort_info
+	    PI_ARGS((pi_file_t *pf, void **dadtap, size_t *sizep));
+
+	/** @brief Read a resource by index
+	 *
+	 * If it exists, the returned data points directly into the file
+	 * structures. Don't dispose or modify it.
+	 *
+	 * @param pf An open file
+	 * @param resindex The resource index
+	 * @param bufp On return, pointer to the resource data block
+	 * @param sizep If not NULL, size of the resource data
+	 * @param restype If not NULL, resource type
+	 * @param resid If not NULL, resource
+	 * @return Negative error code on error
+	 */
+	extern int pi_file_read_resource
+	    PI_ARGS((pi_file_t *pf, int resindex, void **bufp, size_t *sizep,
+		     unsigned long *restype, int *resid));
+
+	/** @brief Read a resource by type and ID
+	 *
+	 * If it exists, the returned data points directly into the file
+	 * structures.
+	 *
+	 * @param pf An open file
+	 * @param restype Resource type
+	 * @param resid Resource ID
+	 * @param bufp On return, pointer to the resource data or NULL
+	 * @param sizep If not NULL, the size of the resource data
+	 * @param resindex If not NULL, on return contains the resource index
+	 * @return Negative error code on error
+	 */
+	extern int pi_file_read_resource_by_type_id
+	    PI_ARGS((pi_file_t *pf, unsigned long restype, int resid,
+		     void **bufp, size_t *sizep, int *resindex));
+
+	/** @brief Checks whether a resource type/id exists in an open file
+	 *
+	 * @param pf An open file
+	 * @param restype Resource type to check
+	 * @param resid Resource ID to check
+	 * @return Non-zero if a resource with same type and id exists
+	 */
+	extern int pi_file_type_id_used
+	    PI_ARGS((const pi_file_t *pf, unsigned long restype, int resid));
+
+	/** @brief Checks whether a record with the given UID exists
+	 *
+	 * @param pf An open file
+	 * @param uid The record UID to look for
+	 * @return Non-zero if a record with the same UID exists
+	 */
+	extern int pi_file_id_used
+	    PI_ARGS((const pi_file_t *pf, recordid_t uid));
+
+	/** @brief Read a record by index
+	 *
+	 * If it exists, the returned data points directly into the file
+	 * structures. Don't dispose or modify it.
+	 *
+	 * @param pf An open file
+	 * @param recindex Record index
+	 * @param bufp On return, pointer to the resource data or NULL
+	 * @param sizep If not NULL, the size of the resource data
+	 * @param recattrs If not NULL, the record attributes
+	 * @param category If not NULL, the record category
+	 * @param recuid If not NULL, the record unique ID
+	 * @return Negative error code on error
+	 */
+	extern int pi_file_read_record
+	    PI_ARGS((pi_file_t *pf, int recindex, void **bufp, size_t *sizep,
+		     int *recattrs, int *category, recordid_t *recuid));
+
+	/** @brief Read a record by unique ID
+	 *
+	 * If it exists, the returned data points directly into the file
+	 * structures. Don't dispose or modify it.
+	 *
+	 * @param pf An open file
+	 * @param recuid The record unique ID
+	 * @param bufp On return, pointer to the resource data or NULL
+	 * @param sizep If not NULL, the size of the resource data
+	 * @param recindex If not NULL, the record index
+	 * @param recattrs If not NULL, the record attributes
+	 * @param category If not NULL, the record category
+	 * @return Negative error code on error
+	 */
+	extern int pi_file_read_record_by_id
+	    PI_ARGS((pi_file_t *pf, recordid_t recuid, void **bufp,
+		     size_t *sizep, int *recindex, int *recattrs, int *category));
+
+#ifndef SWIG
+	extern void pi_file_get_entries
+	    PI_ARGS((pi_file_t *pf, int *entries));
+#endif
+/*@}*/
+
+/** @name Modifying files open for write */
+/*@{*/
+	/* may call these any time before close (even multiple times) */
+	extern int pi_file_set_info
+	    PI_ARGS((pi_file_t *pf, const struct DBInfo *infop));
+
+	/** @brief Set the database's appInfo block
+	 *
+	 * The file takes ownership of the passed data block
+	 *
+	 * @param pf A file open for write
+	 * @param data Pointer to the data or NULL to clear the appInfo block
+	 * @param size Size of the new data block
+	 * @return Negative code on error
+	 */
+	extern int pi_file_set_app_info
+	    PI_ARGS((pi_file_t *pf, void *data, size_t size));
+
+	/** @brief Set the database's sortInfo block
+	 *
+	 * The file takes ownership of the passed data block
+	 *
+	 * @param pf A file open for write
+	 * @param data Pointer to the data or NULL to clear the sortInfo block
+	 * @param size Size of the new data block
+	 * @return Negative code on error
+	 */
+	extern int pi_file_set_sort_info
+	    PI_ARGS((pi_file_t *pf, void *data, size_t size));
+
+	/** @brief Add a resource to a file open for write
+	 *
+	 * The file takes ownership of the passed data block
+	 * Function will return PI_ERR_FILE_ALREADY_EXISTS if resource with
+	 * same type/id already exists
+	 *
+	 * @param pf A file open for write
+	 * @param data The resource data
+	 * @param size The resource size
+	 * @param restype Resource type
+	 * @param resid Resource ID
+	 * @return Negative code on error.
+	 */
+	extern int pi_file_append_resource
+	    PI_ARGS((pi_file_t *pf, void *data, size_t size,
+		     unsigned long restype, int resid));
+
+	/** @brief Add a record to a file open for write
+	 *
+	 * The file takes ownership of the passed data block Function will
+	 * return PI_ERR_FILE_ALREADY_EXISTS if record with same unique ID
+	 * already exists in the database
+	 *
+	 * @param pf A file open for write
+	 * @param data The resource data
+	 * @param size The resource size
+	 * @param recattrs Record attributes
+	 * @param category Record category
+	 * @param recuid Record unique ID (pass 0 to have recuid automatically allocated)
+	 * @return Negative code on error.
+	 */
+	extern int pi_file_append_record
+	    PI_ARGS((pi_file_t *pf, void *buf, size_t size, int recattrs,
+		     int category, recordid_t recuid));
+/*@}*/
+
+/** @name File transfer utilities */
+/*@{*/
+	/** @brief Retrieve a file from the handheld
+	 *
+	 * You must first create the local file using pi_file_create()
+	 *
+	 * @param pf A file open for write
+	 * @param socket Socket to the connected handheld
+	 * @param cardno Card number the file resides on (usually 0)
+	 * @param report_progress Progress function callback or NULL (see #pi_progress_t structure)
+	 * @return Negative code on error
+	 */
+	extern int pi_file_retrieve
+	    PI_ARGS((pi_file_t *pf, int socket, int cardno,
+			progress_func report_progress));
+
+	/** @brief Install a new file on the handheld
+	 *
+	 * You must first open the local file with pi_file_open()
+	 *
+	 * @param pf An open file
+	 * @param socket Socket to the connected handheld
+	 * @param cardno Card number to install to (usually 0)
+	 * @param report_progress Progress function callback or NULL (see #pi_progress_t structure)
+	 * @return Negative code on error
+	 */
+	extern int pi_file_install
+	    PI_ARGS((pi_file_t *pf, int socket, int cardno,
+			progress_func report_progress));
+
+	/** @brief Install a new file on the handheld or merge with an existing file
+	 *
+	 * The difference between this function and pi_file_install() is
+	 * that if the file already exists on the handheld, pi_file_merge()
+	 * will append data to the existing file. For resource files, all
+	 * resources from the local file are sent to the handheld. If
+	 * resources with the same type/ID exist in the handheld file, they
+	 * are replaced with the new one.
+	 *
+	 * You must first open the local file with pi_file_open()
+	 *
+	 * @param pf An open file
+	 * @param socket Socket to the connected handheld
+	 * @param cardno Card number to install to (usually 0)
+	 * @param report_progress Progress function callback or NULL (see #pi_progress_t structure)
+	 * @return Negative code on error
+	 */
+	extern int pi_file_merge
+	    PI_ARGS((pi_file_t *pf, int socket, int cardno,
+			progress_func report_progress));
+/*@}*/
+
+/** @name Time utilities */
+/*@{*/
+	/** @brief Convert Unix time to Palm OS time
+	 *
+	 * @param t Unix time value
+	 * @return Time value with Palm OS timebase
+	 */
+	extern unsigned long unix_time_to_pilot_time
+	    PI_ARGS((time_t t));
+
+	/** @brief Convert Palm OS time to Unix time
+	 *
+	 * @param raw_time Time value expressed in Palm OS timebase (seconds from 01-JAN-1904, 00:00)
+	 * @return Unix time
+	 */
+	extern time_t pilot_time_to_unix_time
+	    PI_ARGS((unsigned long raw_time));
+/*@}*/
+
+#ifdef __cplusplus
+}
+#endif
+#endif