//
-// $Id: fcgio.h,v 1.4 2001/06/20 16:05:55 robs Exp $
+// Provides support for FastCGI via C++ iostreams.
//
-// Allows you communicate with FastCGI streams using C++ iostream
-// objects
-//
-// defines classes fcgi_streambuf, fcgi_ostream, fcgi_istream
-// you can redefine cin, cout, cerr or use your own custom
-// FCGI stream names.
-//
-// ORIGINAL AUTHOR: George Feinberg
-//
-//
-// REWRITTEN BY: Michael Richards 06/20/1999
-// -added cin support
-// -added ability to replace cin/cout so existing code only
-// needs to include the header file and use the normal
-// cin/cout. This has been altered as of 2/2000, see below.
-// -added buffered read support which is required for ungets.
-//
-//
-// REWRITTEN AGAIN BY: Michael Shell 02/23/2000
-//
-// Previous versions of this code had problems.
-// Two hellish bugs have been fixed and there is now full
-// buffering for both input and output streams.
-//
-// - fixed signed char bug in underflow() that would
-// cause a false EOF to be flagged when reading binary
-// data. Uploading short binary files via <input type=file
-// which uses multipart/form-data encoding would reveal
-// this bug. Also could be triggered by hackers
-// sending binary data instead of legitimate form data,
-// in which case the hung network connection, depending on
-// how the FCGI application server handles things, could
-// form the basis for a stupid denial of service attack.
-// - fixed code to properly use the get and put buffers via
-// underflow() and overflow() NOT xsgetn() and xsputn() as
-// was done before. Because of this, the previous
-// version would often drop data, especially if the
-// user did an initial getline() followed by a read().
-// - added the attach() method and a parameterless
-// constructor so that you can declare fcgi_iostream
-// objects and attach() to them later - after accept().
-// - enhanced docs to include examples that actually work.
-// - removed any predefined redefinitions of cin,cout,cerr.
-// The example shows how you can use these names if you
-// want (via properly placed #undefs) or use ones of your
-// choosing (such as fin,fout,ferr). This may be very
-// helpful when testing code. Also, as a result, you
-// no longer have to place fcgio2.h in any special
-// order in your #includes.
-// - added an experimental method drain() to istream which
-// allows the user to drain the get buffer. This is
-// designed to provide users with a way to drain the get
-// buffer prior to using a read function from the FCGI
-// library in applications which mix I/O methods. i.e.
-// it is the input equivalent to flush(). It does not
-// read from the FCGI stream, but gets only characters
-// already in the istream buffer. Mixing I/O methods is
-// not recommended since this iostream implementation
-// is complete and should provide you with everything
-// you need.
-//
-//
-// NOTES: encapsulates the FastCGI protocol in an iostream via a
-// nice custom streambuf. Very nice, very robust, and very powerful.
+// $Id: fcgio.h,v 1.15 2002/02/25 13:16:11 robs Exp $
//
// This work is based on routines written by George Feinberg. They
// have been mostly re-written and extensively changed by
//
// Rewritten again with bug fixes and numerous enhancements by
// Michael Shell.
+//
+// And rewritten again by Rob Saccoccio.
//
// Special Thanks to Dietmar Kuehl for his help and the numerous custom
// streambuf examples on his web site.
//
// Copyright (c) 2000 Tux the Linux Penguin
+// Copyright (c) 2001 Rob Saccoccio and Chelsea Networks
//
// You are free to use this software without charge or royalty
// as long as this notice is not removed or altered, and recognition
//
// This code is offered as-is without any warranty either expressed or
// implied; without even the implied warranty of MERCHANTABILITY or
-// FITNESS FOR A PARTICULAR PURPOSE.
-// If it breaks, you get to keep both halves.
-
-
-// BEGIN EXAMPLE CODE: test_fcgio2.cpp
-/*
-// This code uses the fcgiapp interface to show a little bit more
-// complexity and to demonstrate the fact that with fcgio2 and just
-// a few more lines of code (like FCGX_Init etc.) you can easily
-// make FastCGI programs without needing wrapper functions.
-// You can use the fcgi_stdio interface if you you want a
-// simpler accept(). However note that the fcgio2 interface
-// removes the need for the fcgi_stdio wrapper functions.
-// i.e. Why override printf when you aren't going to use it anyway?
-// Also, be aware that because of iostream buffering, you must take
-// care when mixing FCGI iostream I/O with the FCGI library I/O
-// commands (such as printf). Be sure to flush() any open
-// fcgi_ostreams prior to using commands such as printf. This is true
-// even on systems which have the C I/O commands synced with C++
-// iostreams, such as Linux, because the FCGI wrapper printf, etc. are
-// not the same as the "normal" printf etc. It is recommended that you
-// not use any FCGI library input (read) commands if you use
-// fcgi_istream (cin) input as there is no easy way to "flush" (drain)
-// an istream get buffer. However, an experimental istream method
-// drain() has been provided to istream for those of you who need to
-// do mixed input. There should be no need to do mixed I/O as the
-// fcgio2 iostream implementation is complete.
-
-#include <stdlib.h>
-#include "fcgio.h" // fcgio.h includes fcgiapp.h
- // however you must include fcgi_stdio.h if
- // you want to use it as fcgio.h does not
- // include it for you
-
-#undef cin // remember you have to undo the stuff predefined
-#undef cout // for cin, cout, cerr if you wish to use these
-#undef cerr // names for your FastCGI streams
-
-int main(void)
-{
-
- int count = 0;
-
- // I can create/declare my objects here, but I don't dare use them
- // until I set them up with attach().
-
- // note that version 1.0 of fcgio used fcgio_istream & fcgio_ostream
- // we made a little change to the names in V2.00 for clarity.
- fcgi_istream cin; // you do not *HAVE* to use these names, you
- fcgi_ostream cout; // could use other stream names of your choice
- fcgi_ostream cerr; // don't forget that the input is
- // fcgi_*I*stream class
-
- FCGX_Request request; // here is our request structure
-
- // get everything ready for the customers
- FCGX_Init();
-
- FCGX_InitRequest(&request,0,0);
-
-
- // let the games begin
- while(FCGX_Accept_r(&request) >= 0)
- {
- count++;
-
- cout.attach(request.out); // now I know my pointer values for
- cerr.attach(request.err); // this request. attach to them
- cin.attach(request.in);
- // attach will initialize everything
- // alternatively, you could declare the streams here and the
- // constructor with the (FCGX_Stream *str) parameter would
- // do the same job as attach
-
- // If you are using fcgi_stdio.h, the equivalent command would
- // be cout.attach(FCGI_stdout->fcgx_stream);
- // and so forth for cin,cerr using FCGI_stdin and FCGI_stderr
- // respectively.
-
-
- // now I can fire at will:
- cout << "Content-type: text/html\r\n\r\n"
- << "<title> FastCGI cin, cout, cerr tester </title>\r\n"
- << "<h1><center> FastCGI C++ IOstream test: "
- << "It works! </center></h1>\r\n";
- cout << "<h4><center><i> Total served by this task: "
- << count << "</i></center></h4>\r\n";
-
-// didn't use cin or cerr in this example.
-
-// it is good practice to flush the buffers.
-// use cout.flush() if you don't want the line feed.
-
- cout << endl;
-
-// there is no cxxx.close() and you do not need it with the fcgio
-// interface. You would need to call cxxx.close() if cxxx was an
-// fstream based object and attached to a file descripter you got
-// from a command like fd=open(blah). (GNU (Linux) based fstreams
-// support this) Then you need to call cxxx.close() before you
-// close the physical file with close(fd). If doing this with
-// fstream objects, you should call cxxx.clear() after
-// attach(fd) as the file descriptor attach is not as complete in
-// initialization as our fcgi_iostream attach()
-// If you don't understand any of this, don't worry about it and
-// forget I even mentioned it.
-
- // all done with this request
- FCGX_Finish_r(&request);
-
- // do the next request
- }
- return (1);
-}
-
-*/
-
-// END EXAMPLE CODE
-
-/*------------------------------------------------------------------*/
-
+// FITNESS FOR A PARTICULAR PURPOSE. If it breaks, you get to keep
+// both halves.
#ifndef FCGIO_H
#define FCGIO_H
-#include <iostream.h>
+#include <iostream>
+#include "fcgiapp.h"
+
+#ifndef DLLAPI
#ifdef _WIN32
-#define DLLAPI __declspec(dllexport)
+#define DLLAPI __declspec(dllimport)
+#else
+#define DLLAPI
+#endif
#endif
-#include <fcgiapp.h>
-
-// we aren't pulling from the heap, so it is best not o make it too big
-#define FCGIO_BUFSIZE 200
+#if ! HAVE_STREAMBUF_CHAR_TYPE
+typedef char char_type;
+#endif
-// FastCGI streambuf replacement. Implements low level I/O to the
-// FastCGI C functions so our higher level iostreams will talk
-// in the FastCGI protocol
-class fcgi_streambuf : public streambuf
+/*
+ * fcgi_streambuf
+ */
+class DLLAPI fcgi_streambuf : public std::streambuf
{
- public:
- // constructor
- fcgi_streambuf(void);
- ~fcgi_streambuf();
+public:
- // handles allocation of buffers by doing nothing since buffer
- // allocation isn't needed
- virtual int doallocate();
+ // Note that if no buf is assigned (the default), iostream methods
+ // such as peek(), unget() and putback() will fail. If a buf is
+ // assigned, I/O is a bit less effecient and output streams will
+ // have to be flushed (or the streambuf destroyed) before the next
+ // call to "accept".
+ fcgi_streambuf(FCGX_Stream * fcgx, char * buf, int len);
+
+ fcgi_streambuf(char_type * buf, std::streamsize len);
+
+ fcgi_streambuf(FCGX_Stream * fcgx = 0);
- // gets data (upto the given maximum) from the get buffer and
- // copies it to the given char array. Returns the number of chars
- // written or -1 on error. A returned value less than the given
- // maximum, assuming the user requested at least one char,
- // indicates that the get buffer is empty. The underflow() method
- // is never called to refill the get buffer, so this method can be
- // used to drain the get buffer. It is used to form an istream
- // drain() method which is the input equivalent to flush().
- virtual int drain_strm(char *,int);
+ ~fcgi_streambuf(void);
- // let's us know if this strembuf has been initialized
- virtual int isstrmdefined(void);
+ int attach(FCGX_Stream * fcgx);
- // (for writers) empties the put buffer and possibly an
- // overflow char into the FCGI interface
- virtual int overflow(int);
-
- // bogus routine in case somebody thinks they know
- // better and calls it. We currently are happy with
- // our static buffer.
- virtual streambuf * setbuf(char *, int);
+protected:
- // initializes the buffering and FCGI interface
- virtual void stream_initialize(FCGX_Stream *,int);
+ // Consume the put area (if buffered) and c (if c is not EOF).
+ virtual int overflow(int);
- // (for writers) flushes the put buffer into the FCGI
- // interface and then flushes the FCGI interface
+ // Flush the put area (if buffered) and the FCGX buffer to the client.
virtual int sync();
- // (for readers) fills the get buffer with data from the
- // FCGI interface
+ // Remove and return the current character.
+ virtual int uflow();
+
+ // Fill the get area (if buffered) and return the current character.
virtual int underflow();
- private:
- // pointer to our underlying FCGI interface
- FCGX_Stream * fcgx_strm;
+ // Use a buffer. The only reasons that a buffer would be useful is
+ // to support the use of the unget()/putback() or seek() methods. Using
+ // a buffer will result in less efficient I/O. Note: the underlying
+ // FastCGI library (FCGX) maintains its own input and output buffers.
+ virtual std::streambuf * setbuf(char_type * buf, std::streamsize len);
- // our buffer
- static int buffersize;
- char buffer[FCGIO_BUFSIZE];
+ virtual std::streamsize xsgetn(char_type * s, std::streamsize n);
+ virtual std::streamsize xsputn(const char_type * s, std::streamsize n);
- // little flag so that we can tell if the
- // fcgi_str pointer was ever set
- int defined;
-};
+private:
-int fcgi_streambuf::buffersize = FCGIO_BUFSIZE;
+ FCGX_Stream * fcgx;
-// Here's the istream class definition.
-class fcgi_istream : public istream
-{
- public:
- fcgi_istream();
- fcgi_istream(FCGX_Stream *str);
- ~fcgi_istream();
+ // buf is just handy to have around
+ char_type * buf;
- // connects the fcgi_streambuf of an existing fcgi_istream
- // object to a given FCGI interface
- virtual void attach(FCGX_Stream *str);
+ // this isn't kept by the base class
+ std::streamsize bufsize;
+
+ void init(FCGX_Stream * fcgx, char_type * buf, std::streamsize bufsize);
- // allows you to drain down the streambuf buffer. It will not
- // read any chars from the FCGI interface. You can repeatedly
- // call drain() to empty the get buffer prior to using a
- // FCGI library function to ensure syncronization of the
- // reads. i.e. it flushes the input stream
- // This method should be considered both nonstandard and
- // experimental. It's use is entirely optional to the user,
- // but could be very helpful for applications which use
- // both istream and FCGI library based reads on a single
- // FCGI interface and need a way to sync the reads.
- // It copies upto the given number of chars into the given
- // char array. It returns the number of chars written or
- // -1 on error. If the number of chars written is less than
- // the number the user requested, the get buffer is empty.
- // This method does not alter or check any of the input
- // status flags such as EOF or FAIL since it does not interact
- // with the underlying FCGI interface at all - it only reads from
- // the get buffer.
- virtual int drain(char *,int);
+ void reset(void);
+};
- // lets us know if this object has been initialized
- virtual int isdefined(void);
+/*
+ * fcgi_istream - deprecated
+ */
+class DLLAPI fcgi_istream : public std::istream
+{
+public:
- private:
- // FastCGI streambuf
- fcgi_streambuf fcgi_strmbuf;
+ // deprecated
+ fcgi_istream(FCGX_Stream * fcgx = 0);
+
+ // deprecated
+ ~fcgi_istream(void) {}
-};
+ // deprecated
+ virtual void attach(FCGX_Stream * fcgx);
+private:
+ fcgi_streambuf fcgi_strmbuf;
+};
-// Here's the ostream class definition.
-class fcgi_ostream : public ostream
+/*
+ * fcgi_ostream - deprecated
+ */
+class DLLAPI fcgi_ostream : public std::ostream
{
- public:
- fcgi_ostream(void);
- fcgi_ostream(FCGX_Stream *str);
- ~fcgi_ostream();
+public:
+
+ // deprecated
+ fcgi_ostream(FCGX_Stream * fcgx = 0);
+
+ // deprecated
+ ~fcgi_ostream(void) {}
- // connects the fcgi_streambuf of an existing fcgi_ostream
- // object to a given FCGI interface
- virtual void attach(FCGX_Stream *str);
+ // deprecated
+ virtual void attach(FCGX_Stream *fcgx);
- // lets us know if this object has been initialized
- virtual int isdefined(void);
+private:
- private:
- // FastCGI streambuf
fcgi_streambuf fcgi_strmbuf;
};
-#endif FCGIO_H
+#endif /* FCGIO_H */
projects / catagits/fcgi2.git / blobdiff