io_stream.h

   1 /*
   2  * Copyright (c) 2001, Robert Collins.
   3  *
   4  *     This program is free software; you can redistribute it and/or modify
   5  *     it under the terms of the GNU General Public License as published by
   6  *     the Free Software Foundation; either version 2 of the License, or
   7  *     (at your option) any later version.
   8  *
   9  *     A copy of the GNU General Public License can be found at
  10  *     http://www.gnu.org/
  11  *
  12  * Written by Robert Collins  <rbtcollins@hotmail.com>
  13  *
  14  */
  15
  16 #ifndef _IO_STREAM_H_
  17 #define _IO_STREAM_H_
  18
  19 /* this is the parent class for all IO operations. It's flexable enough to be cover for
  20  * HTTP access, local file access, and files being extracted from archives.
  21  * It also encapsulates the idea of an archive, and all non-archives become the special
  22  * case.
  23  */
  24
  25 #include <stdio.h>
  26 #include "String++.h"
  27 class IOStreamProvider;
  28
  29 /* Some things don't fit cleanly just - TODO
  30  * make mkdir_p fit in the hierarchy
  31  */
  32
  33 //Where is this defined?
  34 typedef signed long ssize_t;
  35
  36 #if __GNUC__
  37 #define _ATTR_(foo) __attribute__ foo
  38 #else
  39 #define _ATTR_(foo)
  40 #endif
  41
  42 typedef enum
  43 {
  44   PATH_TO_DIR,
  45   PATH_TO_FILE
  46 }
  47 path_type_t;
  48
  49 typedef enum
  50 {
  51   IO_STREAM_INVALID,
  52   IO_STREAM_STREAM,
  53   IO_STREAM_COMPRESS,
  54   IO_STREAM_ARCHIVE
  55 }
  56 io_stream_type_t;
  57
  58 typedef enum
  59 {
  60   IO_STREAM_SYMLINK,
  61   IO_STREAM_HARDLINK
  62 }
  63 io_stream_link_t;
  64
  65 typedef enum
  66 {
  67   IO_SEEK_SET = SEEK_SET,
  68   IO_SEEK_END = SEEK_END,
  69   IO_SEEK_CUR = SEEK_CUR
  70 }
  71 io_stream_seek_t;
  72
  73 class io_stream
  74 {
  75 public:
  76   /* Register a new io_stream provider */
  77   static void registerProvider (IOStreamProvider &, String const &urlscheme);
  78   /* create a new stream from an existing one - used to get
  79    * decompressed data
  80    * or open archives.
  81    * will return NULL if there is no sub-stream available (ie (peek()
  82    * didn't match any known magic number) && nextfilename () = NULL
  83    */
  84   static io_stream *factory (io_stream *);
  85   /* open a stream by url. The particular stream type returned
  86    * will depend on the url passed.
  87    * ie for file:// it will be a disk file.
  88    * for ftp:// it will perform an upload to a ftp site.
  89    * the second parameter - mode can specify r|w && t|b. Other flags are not currently
  90    * supported.
  91    * Automatic decompression does not occur. Compressed files will return a io_stream
  92    * from archive::decompress. This behaviour is by design - to allow deliberate access
  93    * to the compressed data.
  94    * To create a stream that will be compressed, you should open the url, and then get a new stream
  95    * from archive::compress.
  96    * If a stream is opened for reading, and it's an archive, the next_file_name method
  97    * will return non-NULL. To access the files within the archive use io_stream::factory
  98    * to create a new stream that will read from the archive.
  99    */
 100   static io_stream *open (String const &, String const &);
 101   static int remove (String const &);
 102   static int exists (String const &);
 103   /* moves physical stream source to dest. A copy will be attempted if a
 104    * pointer flip fails.
 105    */
 106   static int move (String const &, String const &);
 107   /* ensure that we have access to the entire path */
 108   /* Create a directory, and any needed parent directories.
 109    * returns 1 on failure.
 110    */
 111   static int mkpath_p (path_type_t, String const &);
 112   /* link from, to, type. Returns 1 on failure */
 113   static int mklink (String const &, String const &, io_stream_link_t);
 114   /* copy from stream to stream - 0 on success */
 115   static ssize_t copy (io_stream *, io_stream *);
 116   /* TODO: we may need two versions of each of these:
 117      1 for external use - when the path is known
 118      1 for inline use, for example to set the mtime of a file being written
 119      into a tarball
 120    */
 121   /* set the modification time of a file - returns 1 on failure
 122    * may distrupt internal state - use after all important io is complete
 123    */
 124   virtual int set_mtime (int) = 0;
 125   /* get the mtime for a file TODO make this a stat(0 style call */
 126   virtual int get_mtime () = 0;
 127   /* How long is the file? 0 means check error(). if error() is 0, the file
 128    * is 0 bytes long. Otherwise the file length cannot be determined
 129    */
 130   virtual size_t get_size () = 0;
 131   /* read data (duh!) */
 132   virtual ssize_t read (void *buffer, size_t len) = 0;
 133   /* provide data to (double duh!) */
 134   virtual ssize_t write (const void *buffer, size_t len) = 0;
 135   /* read data without removing it from the class's internal buffer */
 136   virtual ssize_t peek (void *buffer, size_t len) = 0;
 137   /* ever read the f* functions from libc ? */
 138   virtual long tell () = 0;
 139   virtual int seek (long, io_stream_seek_t) = 0;
 140   /* try guessing this one */
 141   virtual int error () = 0;
 142   /* hmm, yet another for the guessing books */
 143   virtual char *gets (char *, size_t len);
 144   /* what sort of stream is this?
 145    * known types are:
 146    * IO_STREAM_INVALID - not a valid stream.
 147    * IO_STREAM_STREAM - just another stream.
 148    * IO_STREAM_COMPRESS - a compressed or compressing stream.
 149    * IO_STREAM_ARCHIVE - an archive of some sort, with > 0 files.
 150    * this is a crutch for real runtime type evaluation.
 151    */
 152   /* Find out the next stream name -
 153    * ie for foo.tar.gz, at offset 0, next_file_name = foo.tar
 154    * for foobar that is an archive, next_file_name is the next
 155    * extractable filename.
 156    */
 157 //  virtual const char* next_file_name() = NULL;
 158   /* if you are still needing these hints... give up now! */
 159   virtual ~ io_stream () = 0;
 160
 161   io_stream& operator << (io_stream&);
 162
 163 protected:
 164   void operator= (const io_stream &);
 165     io_stream () : destroyed (0)
 166   {
 167   };
 168   io_stream (const io_stream &);
 169   unsigned int destroyed;
 170 private:
 171   static int move_copy (String const &, String const &);
 172 };
 173
 174 #endif /* _IO_STREAM_H_ */