/*-*-c++-*-
* $Id: rfsv.h,v 1.24 2002/07/14 06:35:33 felfert Exp $
*
* This file is part of plptools.
*
* Copyright (C) 1999 Philip Proudman <philip.proudman@btinternet.com>
* Copyright (C) 1999-2002 Fritz Elfert <felfert@to.com>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program 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 General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
*/
#ifndef _RFSV_H_
#define _RFSV_H_
#include <deque>
#include <string>
#include <Enum.h>
#include <plpdirent.h>
#include <bufferstore.h>
typedef std::deque<class PlpDirent> PlpDir;
class ppsocket;
class PlpDrive;
const int RFSV_SENDLEN = 2000;
/**
* Defines the callback procedure for
* progress indication of copy operations.
*/
typedef int (*cpCallback_t)(void *, u_int32_t);
class rfsv16;
class rfsv32;
/**
* A helper class for storing
* intermediate internal information in rfsv16 and
* rfsv32 .
* @internal
*/
class rfsvDirhandle {
friend class rfsv16;
friend class rfsv32;
private:
u_int32_t h;
bufferStore b;
};
/**
* 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 = 0000,
PSI_O_WRONLY = 0001,
PSI_O_RDWR = 0002,
};
/**
* The known modes for file creation.
*/
enum open_mode {
PSI_O_CREAT = 00100,
PSI_O_EXCL = 00200,
PSI_O_TRUNC = 01000,
PSI_O_APPEND = 02000,
PSI_O_SHARE = 04000,
};
/**
* 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 EPOC and SIBO. */
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 only. */
PSI_A_NORMAL = 0x0040,
PSI_A_TEMP = 0x0080,
PSI_A_COMPRESSED = 0x0100,
/** Attributes, valid on SIBO only. */
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.
*
* @param attr The open mode. Use @ref opMode to convert a combination of @ref open_flags
* and @ref open_mode to the machine-specific representation.
* @param name The name of the file to open.
* @param handle The handle for usage with @ref fread ,
* @ref fwrite , @ref fseek or @ref fclose is returned here.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> fopen(const u_int32_t attr, const char * const name, u_int32_t &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 fwrite , @ref fseek or @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(u_int32_t &handle, std::string &name) = 0;
/**
* Creates a named file.
*
* @param attr The open mode. Use @ref opMode to convert a combination of @ref open_flags
* and @ref open_mode to the machine-specific representation.
* @param name The name of the file to create.
* @param handle The handle for usage with @ref fread ,
* @ref fwrite , @ref fseek or @ref fclose is returned here.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> fcreatefile(const u_int32_t attr, const char * const name, u_int32_t &handle) = 0;
/**
* Creates an named file, overwriting an existing file.
*
* @param attr The open mode. Use @ref opMode to convert a combination of @ref open_flags
* and @ref open_mode to the machine-specific representation.
* @param name The name of the file to create.
* @param handle The handle for usage with @ref fread ,
* @ref fwrite , @ref fseek or @ref fclose is returned here.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> freplacefile(const u_int32_t attr, const char * const name, u_int32_t &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 u_int32_t handle) = 0;
/**
* Reads a directory on the Psion.
* The returned STL deque of @ref PlpDirent contains all
* requested directory entries.
*
* @param name The name of the directory
* @param ret An STL deque of @ref PlpDirent entries.
*
* @returns A Psion error code (One of enum @ref rfsv::errs ).
*/
virtual Enum<errs> dir(const char * const name, PlpDir &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, u_int32_t &attr) = 0;
/**
* Retrieves attributes, size and modification time of a file on the Psion.
*
* @param name The name of the file.
* @param e @ref PlpDirent object, filled with the information on return.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> fgeteattr(const char * const name, PlpDirent &e) =0;
/**
* @param name
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> fsetattr(const char * const name, const u_int32_t seta, const u_int32_t 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, u_int32_t &count) = 0;
/**
* Retrieves available drives on the Psion.
* @p devbits On return, for every exiting drive, a bit is set in this
* variable. The lowest bit represents drive A:.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> devlist(u_int32_t &devbits) = 0;
/**
* Retrieves details about a drive.
*
* @param drive The drive character of the drive to get details from
* (e.g: 'C', 'D' etc.).
* (0 represents A:, 1 is B: and so on ...)
* @param dinfo A @ref PlpDrive object which is filled with the drive's
* information upon return.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> devinfo(const char drive, PlpDrive &dinfo) = 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 u_int32_t handle, unsigned char * const buffer, const u_int32_t len, u_int32_t &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 u_int32_t handle, const unsigned char * const buffer, const u_int32_t len, u_int32_t &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. If the callback function
* returns 0, the operation is aborted and E_PSI_FILE_CANCEL is returned.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> copyFromPsion(const char *from, const char *to, void *, cpCallback_t func) = 0;
/**
* Copies a file from the Psion to the local machine.
*/
virtual Enum<rfsv::errs> copyFromPsion(const char *from, int fd, cpCallback_t cb) = 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. If the callback function
* returns 0, the operation is aborted and E_PSI_FILE_CANCEL is returned.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> copyToPsion(const char * const from, const char * const to, void *, cpCallback_t func) = 0;
/**
* Copies a file from the Psion to the Psion.
* On the EPOC variants, this runs much faster than reading
* data from the Psion and then writing it back to the Psion, since
* data transfer is handled locally on the Psion.
*
* @param from Name of the file to be copied.
* @param to Name of the destination file.
* @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. If the callback function
* returns 0, the operation is aborted and E_PSI_FILE_CANCEL is returned.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> copyOnPsion(const char * const from, const char * const to, void *, 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 u_int32_t handle, const u_int32_t 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 u_int32_t handle, const int32_t offset, const u_int32_t mode, u_int32_t &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;
/**
* Open a directory for reading with readdir.
*
* @param attr A combination of PSI_A_.. flags, representing the desired types
* of entries to be returned when calling @ref readdir .
* @param name The name of the directory
* @param handle A handle to be used with @ref readdir and @ref closedir .
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> opendir(const u_int32_t attr, const char * const name, rfsvDirhandle &handle) = 0;
/**
* Read directory entries.
* This method reads entries of a directory, previously
* opened with @ref opendir .
*
* @param handle A handle, obtained by calling @ref opendir .
* @param entry The entry information is returned here.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> readdir(rfsvDirhandle &handle, PlpDirent &entry) = 0;
/**
* Close a directory, previously opened with @ref opendir.
*
* @param handle A handle, obtained by calling @ref opendir .
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> closedir(rfsvDirhandle &handle) = 0;
/**
* Set the name of a Psion Volume (Drive).
*
* @param drive The drive character of the Volume, whose name should be set.
* @param name The new name for that drive.
*
* @returns A Psion error code (One of enum @ref #errs ).
*/
virtual Enum<errs> setVolumeName(const char drive, 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:
*
* 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.
*
* The rest (3 characters) are machine specific:
*
* 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.
*
*
* @param attr the generic file attribute.
*
* @returns Pointer to static textual representation of file attributes.
*
*/
std::string attr2String(const u_int32_t attr);
/**
* Converts an open-mode (A combination of the PSI_O_ constants.)
* from generic representation to the machine-specific representation.
*
* @param mode The generic open mode.
*
* @returns The machine specific representation for use with
* @ref fopen , @ref fcreatefile and @freplacefile.
*/
virtual u_int32_t opMode(const u_int32_t mode) = 0;
/**
* Utility method, converts '/' to '\'.
*/
static std::string convertSlash(const std::string &name);
/**
* Retrieve speed of serial link.
*
* @returns The speed of the serial link in baud or -1 on error.
*/
int getSpeed();
/**
* Retrieves the protocol version.
*
* @returns Either 3 or 5 representing Series 3 (SIBO) or Series 5 (EPOC)
*/
virtual int getProtocolVersion() = 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;
int32_t serNum;
};
#endif
/*
* Local variables:
* c-basic-offset: 4
* End:
*/
| Generated by: felfert@usw-pr-shell1.sourceforge.net on Sat Aug 10 18:46:04 2002, using kdoc 2.0a36. |