cdsa/cdsa_utilities/streams.h

   1 /*
   2  * Copyright (c) 2000-2001 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18
  19 //
  20 // streams.h - lightweight source and sink objects
  21 //
  22 #ifndef _H_STREAMS
  23 #define _H_STREAMS
  24
  25 #include "unix++.h"
  26
  27
  28 namespace Security {
  29
  30 using UnixPlusPlus::FileDesc;
  31
  32
  33 //
  34 // An abstract Source object.
  35 // Source can yield data when its produce method is called. Produce can yield
  36 // anything between zero and length bytes and sets length accordingly.
  37 // If the last call to produce returned zero bytes (and only then), the state method
  38 // will yield an explanation:
  39 //      producing -> we're in business; there just no data quite yet (try again)
  40 //      stalled -> there may be more data coming, but not in the near future;
  41 //                      wait a while then call state again to see
  42 //      endOfData -> no more data will be produced by this Source
  43 // When called *before* the first call to produce, getSize may return the number
  44 // of bytes that all calls to produce will yield together. If getSize returns unknownSize,
  45 // this value cannot be determined beforehand. GetSize *may* yield the number of bytes
  46 // yet to come when called after produce, but this is not guaranteed for all Sources.
  47 //
  48 class Source {
  49 public:
  50     virtual void produce(void *data, size_t &length) = 0;
  51     virtual ~Source() { }
  52
  53     static const size_t unknownSize = size_t(-1);
  54     virtual size_t getSize();
  55
  56     enum State {
  57         producing,              // yielding data (go ahead)
  58         stalled,                // no data now, perhaps more later
  59         endOfData               // end of data (no more data)
  60     };
  61     virtual State state() const;
  62
  63 protected:
  64     State mState;               // auto-regulated state (can be overridden)
  65 };
  66
  67
  68 //
  69 // An abstract Sink object.
  70 // Sinks can cansume data when their consume method is called.
  71 // Sinks cannot refuse data; they always consume all data given to consume.
  72 // There is currently no flow control/throttle mechanism (one will probably
  73 // be added soon).
  74 //
  75 class Sink {
  76 public:
  77     virtual ~Sink() { }
  78     virtual void consume(const void *data, size_t length) = 0;
  79     virtual void setSize(size_t expectedSize);
  80 };
  81
  82
  83 //
  84 // The NullSource produces no data.
  85 //
  86 class NullSource : public Source {
  87 public:
  88     void produce(void *addr, size_t &len);
  89     State state() const;
  90 };
  91
  92
  93 //
  94 // A FileSource reads from a UNIX file or file descriptor.
  95 // Note that getSize will yield the size of the underlying i-node,
  96 // which is usually correct but may not be in the case of simultaneous
  97 // access.
  98 //
  99 class FileSource : public Source, public FileDesc {
 100 public:
 101     FileSource(const char *path, int mode = O_RDONLY) : FileDesc(path, mode) { mState = producing; }
 102     FileSource(int fd) : FileDesc(fd) { mState = producing; }
 103     void produce(void *data, size_t &length);
 104     size_t getSize();
 105 };
 106
 107
 108 //
 109 // A MemorySource yields the contents of a preset contiguous memory block.
 110 //
 111 class MemorySource : public Source {
 112 public:
 113     MemorySource(const void *data, size_t length) : mData(data), mRemaining(length) { }
 114
 115     template <class Data>
 116     MemorySource(const Data &data) : mData(data.data()), mRemaining(data.length()) { }
 117
 118     void produce(void *data, size_t &length);
 119     size_t getSize();
 120     State state() const;
 121
 122 private:
 123     const void *mData;
 124     size_t mRemaining;
 125 };
 126
 127
 128 //
 129 // A NullSink eats all data and discards it quietly.
 130 //
 131 class NullSink : public Sink {
 132 public:
 133     void consume(const void *data, size_t length);
 134 };
 135
 136
 137 //
 138 // A FileSink writes its received data to a UNIX file or file descriptor.
 139 //
 140 class FileSink : public Sink, public FileDesc {
 141 public:
 142     FileSink(const char *path, int mode = O_WRONLY | O_CREAT | O_TRUNC)
 143         : FileDesc(path, mode) { }
 144     FileSink(int fd) : FileDesc(fd) { }
 145     void consume(const void *data, size_t length);
 146 };
 147
 148
 149 //
 150 // MemorySinks collect output in a contiguous memory block.
 151 // This is not often a good idea, so if you find yourself using this,
 152 // consider consuming on-the-fly or streaming to secondary media,
 153 // or (at least) use a BufferFifo instead.
 154 //
 155 class MemorySink : public Sink {
 156 public:
 157     MemorySink() : mBuffer(NULL), mSize(0), mMax(0) { }
 158     ~MemorySink()       { free(mBuffer); }
 159
 160     void consume(const void *data, size_t length);
 161     void setSize(size_t expectedSize);
 162
 163     void *data() const          { return mBuffer; }
 164     size_t length() const       { return mSize; }
 165
 166     void clear()                        { free(mBuffer); mBuffer = NULL; mSize = mMax = 0; }
 167
 168 private:
 169     void grow(size_t newSize);
 170
 171 private:
 172     void *mBuffer;              // buffer base
 173     size_t mSize;               // currently used
 174     size_t mMax;                // currently allocated
 175 };
 176
 177
 178 }       // end namespace Security
 179
 180
 181 #endif _H_STREAMS