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