path: root/lib/rfsv.h

#ifndef _rfsv_h_
#define _rfsv_h_

#include "Enum.h"
#include "psitime.h"

class ppsocket;
class bufferStore;
class bufferArray;

const long RFSV_SENDLEN = 2000;

/**
 * Defines the callback procedure for
 * progress indication of copy operations.
 */
typedef int (*cpCallback_t)(long);

/**
 * Access remote file services of a Psion.
 *
 * rfsv provides an API for accessing file services
 * of a Psion connected via ncpd. This class defines the
 * interface and a small amount of common constants and
 * methods. The majority of implementation is provided
 * by @ref rfsv32 and @ref rfsv16, which implement the
 * variations of the protocol for EPOC and SIBO respectively.
 * Usually, the class @ref rfsvfactory is used to instantiate
 * the correct variant depending on the remote machine,
 * currently connected.
 */
class rfsv {
	public:
		/**
		 * The kown modes for seek.
		 */
		enum seek_mode {
			PSI_SEEK_SET = 1,
			PSI_SEEK_CUR = 2,
			PSI_SEEK_END = 3
		};

		/**
		 * The known modes for file open.
		 */
		enum open_flags {
			PSI_O_RDONLY = 00,
			PSI_O_WRONLY = 01,
			PSI_O_RDWR = 02,
		};

		/**
		 * The known modes for file creation.
		 */
		enum open_mode {
			PSI_O_CREAT = 0100,
			PSI_O_EXCL = 0200,
			PSI_O_TRUNC = 01000,
			PSI_O_APPEND = 02000,
		};

		/**
		 * The known error codes.
		 */
		enum errs {
			E_PSI_GEN_NONE	= 0,
			E_PSI_GEN_FAIL = -1,
			E_PSI_GEN_ARG = -2,
			E_PSI_GEN_OS = -3,
			E_PSI_GEN_NSUP = -4,
			E_PSI_GEN_UNDER = -5,
			E_PSI_GEN_OVER = -6,
			E_PSI_GEN_RANGE = -7,
			E_PSI_GEN_DIVIDE = -8,
			E_PSI_GEN_INUSE = -9,
			E_PSI_GEN_NOMEMORY = - 10,
			E_PSI_GEN_NOSEGMENTS = -11,
			E_PSI_GEN_NOSEM = -12,
			E_PSI_GEN_NOPROC = -13,
			E_PSI_GEN_OPEN = -14,
			E_PSI_GEN_NOTOPEN = -15,
			E_PSI_GEN_IMAGE = -16,
			E_PSI_GEN_RECEIVER = -17,
			E_PSI_GEN_DEVICE = -18,
			E_PSI_GEN_FSYS = -19,
			E_PSI_GEN_START = -20,
			E_PSI_GEN_NOFONT = -21,
			E_PSI_GEN_TOOWIDE = -22,
			E_PSI_GEN_TOOMANY = -23,
			E_PSI_FILE_EXIST = -32,
			E_PSI_FILE_NXIST = -33,
			E_PSI_FILE_WRITE = -34,
			E_PSI_FILE_READ = -35,
			E_PSI_FILE_EOF = -36,
			E_PSI_FILE_FULL = -37,
			E_PSI_FILE_NAME = -38,
			E_PSI_FILE_ACCESS = -39,
			E_PSI_FILE_LOCKED = -40,
			E_PSI_FILE_DEVICE = -41,
			E_PSI_FILE_DIR = -42,
			E_PSI_FILE_RECORD = -43,
			E_PSI_FILE_RDONLY = -44,
			E_PSI_FILE_INV = -45,
			E_PSI_FILE_PENDING = -46,
			E_PSI_FILE_VOLUME = -47,
			E_PSI_FILE_CANCEL = -48,
			E_PSI_FILE_ALLOC = -49,
			E_PSI_FILE_DISC = -50,
			E_PSI_FILE_CONNECT = -51,
			E_PSI_FILE_RETRAN = -52,
			E_PSI_FILE_LINE = -53,
			E_PSI_FILE_INACT = -54,
			E_PSI_FILE_PARITY = -55,
			E_PSI_FILE_FRAME = -56,
			E_PSI_FILE_OVERRUN = -57,
			E_PSI_MDM_CONFAIL = -58,
			E_PSI_MDM_BUSY = -59,
			E_PSI_MDM_NOANS = -60,
			E_PSI_MDM_BLACKLIST = -61,
			E_PSI_FILE_NOTREADY = -62,
			E_PSI_FILE_UNKNOWN = -63,
			E_PSI_FILE_DIRFULL = -64,
			E_PSI_FILE_PROTECT = -65,
			E_PSI_FILE_CORRUPT = -66,
			E_PSI_FILE_ABORT = -67,
			E_PSI_FILE_ERASE = -68,
			E_PSI_FILE_INVALID = -69,
			E_PSI_GEN_POWER = -100,
			E_PSI_FILE_TOOBIG = -101,
			E_PSI_GEN_DESCR = -102,
			E_PSI_GEN_LIB = -103,
			E_PSI_FILE_NDISC = -104,
			E_PSI_FILE_DRIVER = -105,
			E_PSI_FILE_COMPLETION = -106,
			E_PSI_GEN_BUSY = -107,
			E_PSI_GEN_TERMINATED = -108,
			E_PSI_GEN_DIED = -109,
			E_PSI_FILE_HANDLE = -110,

			// Special error code for "Operation not permitted in RFSV16"
			E_PSI_NOT_SIBO = -200,
			// Special error code for "internal library error"
			E_PSI_INTERNAL = -201
		};

		/**
		 * The known file attributes
		 */
		enum file_attribs {
			/** Attributes, valid on both <em>EPOC</em> and <em>SIBO</em>. */
			PSI_A_RDONLY     = 0x0001,
			PSI_A_HIDDEN     = 0x0002,
			PSI_A_SYSTEM     = 0x0004,
			PSI_A_DIR        = 0x0008,
			PSI_A_ARCHIVE    = 0x0010,
			PSI_A_VOLUME     = 0x0020,

			/** Attributes, valid on EPOC <em>only</em>. */
			PSI_A_NORMAL     = 0x0040,
			PSI_A_TEMP       = 0x0080,
			PSI_A_COMPRESSED = 0x0100,

			/** Attributes, valid on SIBO <em>only</em>. */
			PSI_A_READ       = 0x0200,
			PSI_A_EXEC       = 0x0400,
			PSI_A_STREAM     = 0x0800,
			PSI_A_TEXT       = 0x1000,
		};

		virtual ~rfsv();
		void reset();
		void reconnect();

		/**
		 * Retrieves the current connection status.
		 *
		 * @returns The status of the connection.
		 */
		Enum<errs> getStatus();

		/**
		 * Opens a file.
		 *
		 */
		virtual Enum<errs> fopen(const long attr, const char * const name, long &handle) = 0;

		/**
		 * Creates a unique temporary file.
		 * The file is opened for reading and writing.
		 *
		 * @param handle The handle for usage with @ref fread, @ref frwrite, @ref fseek @ref fclose is returned here.
		 * @param name The name of the temporary file is returned here.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> mktemp(long &handle, char * const name) = 0;

		/**
		 * Creates a named file.
		 */
		virtual Enum<errs> fcreatefile(const long attr, const char * const name, long &handle) = 0;

		/**
		 * Creates an named file, overwriting an existing file.
		 */
		virtual Enum<errs> freplacefile(const long attr, const char * const name, long &handle) = 0;

		/**
		 * Close a file on the Psion whih was previously opened/created by using
		 * @ref fopen, @ref fcreatefile, @ref freplacefile or @ref mktemp.
		 *
		 * @param handle A valid file handle.
		 */
		virtual Enum<errs> fclose(const long handle) = 0;

		/**
		 * Reads a directory on the Psion.
		 * The returned array of @ref bufferArray contains one @ref bufferStore element
		 * for each directory entry.
		 * The layout of information data is as follows:
		 * <pre>
		 * 	offset		size	value
		 * 	0		4	Pointer to a PsiTime object, representing the file's modification.
		 * 	4		4	Size in bytes.
		 * 	8		4	Attributes.
		 * 	12		?	Zero terminated file name.
		 * </pre>
		 *
		 * @param name The name of the directory
		 * @param ret Array of @ref bufferStore containing information for directory entries.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> dir(const char * const name, bufferArray &ret) = 0;

		/**
		 * Retrieves the modification time of a file on the Psion.
		 *
		 * @param name Name of the file.
		 * @param mtime Modification time is returned here.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> fgetmtime(const char * const name, PsiTime &mtime) = 0;

		/**
		 * Sets the modification time of a file on the Psion.
		 *
		 * @param name Name of the file whose modification time should be set.
		 * @param mtime The desired modification time.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> fsetmtime(const char * const name, const PsiTime mtime) = 0;

		/**
		 * Retrieves attributes of a file on the Psion.
		 *
		 * @param name Name of the file whose attributes ar to be retrieved.
		 * @param attr The file's attributes are returned here.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> fgetattr(const char * const name, long &attr) = 0;

		/**
		 * Retrieves attributes, size and modification time of a file on the Psion.
		 *
		 * @param name The name of the file.
		 * @param attr The file's attributes are returned here.
		 * @param size The file's size in bytes is returned here.
		 * @param time The file's modification time is returned here.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> fgeteattr(const char * const name, long &attr, long &size, PsiTime &time) =0; 

		/**
		 * @param name
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> fsetattr(const char * const name, const long seta, const long unseta) = 0;

		/**
		 * Counts number of entries in a directory.
		 *
		 * @param name The directory whose entries are to be counted.
		 * @param count The number of entries is returned here.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> dircount(const char * const name, long &count) = 0;
		virtual Enum<errs> devlist(long &devbits) = 0;
		virtual Enum<errs> devinfo(const int dev, long &free, long &total, long &attr, long &uniqueid, char * const name) = 0;


		/**
		 * Reads from a file on the Psion.
		 *
		 * @param handle Handle of the file to read from.
		 * @param buffer The area where to store the data read.
		 * @param len The number of bytes to read.
		 * @param count The number of bytes actually read is returned here.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> fread(const long handle, unsigned char * const buffer, const long len, long &count) = 0;

		/**
		 * Write to a file on the Psion.
		 *
		 * @param handle Handle of the file to read from.
		 * @param buffer The area to be written.
		 * @param len The number of bytes to write.
		 * @param count The number of bytes actually written is returned here.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> fwrite(const long handle, const unsigned char * const buffer, const long len, long &count) = 0;

		/**
		 * Copies a file from the Psion to the local machine.
		 *
		 * @param from Name of the file on the Psion to be copied.
		 * @param to Name of the destination file on the local machine.
		 * @param func Pointer to a function which gets called on every read.
		 * 	This function can be used to show some progress etc. May be set
		 * 	to NULL, where no callback is performed.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> copyFromPsion(const char *from, const char *to, cpCallback_t func) = 0;

		/**
		 * Copies a file from local machine to the Psion.
		 *
		 * @param from Name of the file on the local machine to be copied.
		 * @param to Name of the destination file on the Psion.
		 * @param func Pointer to a function which gets called on every read.
		 * 	This function can be used to show some progress etc. May be set
		 * 	to NULL, where no callback is performed.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> copyToPsion(const char * const from, const char * const to, cpCallback_t func) = 0;

		/**
		 * Resizes an open file on the Psion.
		 * If the new size is greater than the file's
		 * current size, the contents of the added
		 * data is undefined. If The new size is smaller,
		 * the file is truncated.
		 *
		 * @param handle Handle of the file to be resized.
		 * @param size New size for that file.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> fsetsize(const long handle, const long size) = 0;

		/**
		 * Sets the current file position of a file on the Psion.
		 *
		 * @param handle The file handle.
		 * @param offset Position to be seeked to.
		 * @param mode The mode for seeking.
		 * @param resultpos The final file position after seeking is returned here.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> fseek(const long handle, const long offset, const long mode, long &resultpos) = 0;

		/**
		 * Creates a directory on the Psion.
		 *
		 * @param name Name of the directory to be created.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> mkdir(const char * const name) = 0;

		/**
		 * Removes a directory on the Psion.
		 *
		 * @param name Name of the directory to be removed.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> rmdir(const char * const name) = 0;

		/**
		 * Renames a file on the Psion.
		 *
		 * @param oldname Name of the file to be renamed.
		 * @param newname New Name for that file.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> rename(const char * const oldname, const char * const newname) = 0;

		/**
		 * Removes a file on the Psion.
		 *
		 * @param name Name of the file to be removed.
		 *
		 * @returns A Psion error code (One of enum @ref #errs ).
		 */
		virtual Enum<errs> remove(const char * const name) = 0;

		/**
		 * Converts a file attribute @ref rfsv::file_attribs to
		 * human readable format, usable for showing them in directory
		 * listings. The first 7 characters are common to all
		 * machine types:
		 * <pre>
		 * 	Char Nr.	Value
		 * 	0		'd' if a directory,			'-' otherwise.
		 * 	1		'r' if file is readable,		'-' otherwise.
		 * 	2		'w' if file is writeable,		'-' otherwise.
		 * 	3		'h' if file is hidden,			'-' otherwise.
		 * 	4		's' if file is a system file,		'-' otherwise.
		 * 	5		'a' if file is modified (archive flag),	'-' otherwise.
		 * 	6		'v' if file is a volume name,		'-' otherwise.
		 * </pre>
		 * The rest (3 characters) are machine specific:
		 * <pre>
		 * 	Char Nr.	EPOC Value		SIBO Value
		 * 	7		'n' if normal,		'x' if executable,	'-' otherwise.
		 * 	8		't' if temporary,	'b' if a stream,	'-' otherwise.
		 * 	8		'c' if compressed,	't' if a textfile,	'-' otherwise.
		 * </pre>
		 *
		 * @param attr the generic file attribute.
		 *
		 * @returns Pointer to static textual representation of file attributes.
		 *
		 */
		const char * const attr2String(const long attr);
		virtual long opMode(const long mode) = 0;
protected:
		/**
		 * Retrieves the PLP protocol name. Mainly internal use.
		 *
		 * @returns The connection name always "SYS$RFSV"
		 */
		const char *getConnectName();

		ppsocket *skt;
		Enum<errs> status;
		int serNum;
};

#endif