#lang scribble/doc
@; THIS FILE IS GENERATED
@(require scribble/manual)
@(require (for-label (planet neil/scgi:1:0)))
@title[#:version "0.1"]{@bold{scgi}: Web HTTP SCGI and CGI in PLT Scheme}
@author{Neil Van Dyke}


License: @seclink["Legal" #:underline? #f]{LGPL 3} @(hspace 1) Web: @link["http://www.neilvandyke.org/scgi-scheme/" #:underline? #f]{http://www.neilvandyke.org/scgi-scheme/}

@defmodule[(planet neil/scgi:1:0)]

      

@section{Introduction}


      

@emph{Note: This is a PRELIMINARY RELEASE of the @bold{scgi} library.  It is being released early because the functionality currently implemented is needed for testing of a system.  Not all documented functionality is necessarily implemented and tested.  A future release will also have more usage documentation.}


      

The @bold{scgi} library implements fast Web CGI using the SCGI protocol.  This library is used in conjunction with an HTTP server supporting SCGI, such as Apache Server with the @tt{mod_scgi} module.


      

The @bold{scgi} library also supports running as normal Web CGI without any change to source code, such as during development of an application intended to be deployed using SCGI.


      

SCGI was specified by Neil Schemenauer in ``SCGI: A Simple Common Gateway Interface alternative,'' dated 2008-06-23 (http://python.ca/scgi/protocol.txt).


      

An example usage of this library:


      

@verbatim["#! /usr/bin/mzscheme\n#lang scheme/base"]


      

@SCHEMEBLOCK[
(require (planet neil/scgi))

(let ((my-foo (my-open-foo)))

  (cgi (lambda ()
         (and (eq? (cgi-type) 'scgi)
              (my-do-some-init-only-for-scgi)))
       (lambda ()
         (display "Content-type: text/html\r\n\r\n")
         (display "<p>Hello, world</p>"))
       (lambda ()
         (my-close-foo my-foo))))
]


      
        

@subsection{Apache mod_scgi}


        

Note that your Apache Server installation might not have @tt{mod_scgi} module installed or enabled by default.  If you happen to be running Debian Lenny (@tt{stable}) or similar, this module can be installed via the Debian package @tt{libapache2-mod-scgi}.


      
    
      

@section{Interface}


      

@defform[(cgi startup-proc request-proc shutdown-proc)]{
          

Implement CGI.  Normal CGI is used if the @tt{REQUEST_URI} environment variable is defined; otherwise, SCGI is used.


          

@schemevarfont{startup-proc} is a thunk that is evaluated once.  @schemevarfont{request-proc} is evaluated once for each request (which, in normal CGI, is once). @schemevarfont{shutdown-proc} is evaluated once, as processing of all CGI requests has finished.


          

For evaluation of @schemevarfont{request-proc}, the default input and output ports are as with normal CGI, regardless of whether normal CGI or SCGI is in use.


        }

      

@defform[(cgi-content-length)]{
          

In a CGI request context, returns the CGI content length -- the number of bytes that can be read from the default input port -- as integer.


        }

      

@defform[(cgi-content-type)]{}


@defform[(cgi-http-cookie)]{}


@defform[(cgi-http-host)]{}


@defform[(cgi-https)]{}


@defform[(cgi-path-info)]{}


@defform[(cgi-query-string)]{}


@defform[(cgi-remote-user)]{}


@defform[(cgi-request-method)]{}


@defform[(cgi-request-uri)]{}


@defform[(cgi-script-name)]{}


@defform[(cgi-server-name)]{}


@defform[(cgi-server-port)]{
          

In a CGI request context, returns the corresponding CGI value as a string.


        }

      

@defform[(scgi-variables)]{
          

When called in SCGI mode, this procedure yields an alist of SCGI variables with both the key and value of each pair being byte strings.  Calling this procedure in normal CGI mode is an error.


          

Note that normally you will not need to use this procedure, and will instead use procedures like @tt{cgi-request-uri}, which work in both SCGI and normal CGI modes.


        }

      

@defform[(cgi-type)]{
          

Returns a symbol indicating the CGI type: @tt{normal} or @tt{scgi}. Behavior outside of the @tt{cgi} form is undefined.


        }

      

@defform[(cgi-request-id)]{
          

In CGI request context, yields a printable identifying object for the current request that is unique at least for the current requests being handled.  This identifying object is intended to be used in debugging messages.


        }

      

@defform[(end-cgi-request)]{}


@defform[(end-cgi-request/error)]{
          

In a CGI context, !!! (NOTE: THIS IS NOT YET FULLY IMPLEMENTED.)


        }

      

@defform[(stop-cgi-service-immediately)]{
          

Stops processing all CGI requests.  This works only within the @schemevarfont{request-proc} of the @tt{cgi} form.


        }

    
      

@section{History}


      

@itemize[

@item{Version 0.1 --- 2010-05-25 --- PLaneT @tt{(1 0)}
            

Initial release.  Preliminary.


          }



]


    

@section[#:tag "Legal"]{Legal}



Copyright (c) 2010 Neil Van Dyke.  This program is Free Software; Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License (LGPL 3), 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 http://www.gnu.org/licenses/ for details.  For other licenses and consulting, please contact the author.