src/lib/cgi.sig

   1 (* Mosmlcgi -- Support for writing CGI scripts in Moscow ML
   2
   3  (c) Jonas Barklund, Computing Science Dept., Uppsala University, 1996.
   4      Documentation and support for file upload added by Peter Sestoft.
   5
   6  --------
   7  Ported to SML/NJ by Dave MacQueen (7 Apr 1998).
   8  Tweaked to work with a saved heap image by Adam Chlipala (2003).
   9
  10 *)
  11
  12 signature CGI =
  13 sig
  14
  15 val init : unit -> unit
  16
  17 (* 1. Accessing the fields or parameters of a CGI call *)
  18
  19 val cgi_fieldnames : unit -> string list
  20 val cgi_field_strings : string -> string list;
  21 val cgi_field_string  : string -> string option;
  22 val cgi_field_integer : string * int -> int;
  23
  24 (* 2. Accessing parts in multipart/form-data; form-based file upload *)
  25
  26 val cgi_partnames : unit -> string list
  27
  28 type part
  29 val cgi_part  : string -> part option
  30 val cgi_parts : string -> part list
  31
  32 val part_fieldnames    : part -> string list
  33 val part_type          : part -> string option
  34 val part_data          : part -> string
  35 val part_field_strings : part -> string -> string list
  36 val part_field_string  : part -> string -> string option
  37 val part_field_integer : part -> string * int -> int
  38
  39 (* 3. Administrative information *)
  40
  41 val cgi_server_software   : unit -> string option;
  42 val cgi_server_name       : unit -> string option;
  43 val cgi_gateway_interface : unit -> string option;
  44 val cgi_server_protocol   : unit -> string option;
  45 val cgi_server_port       : unit -> string option;
  46 val cgi_request_method    : unit -> string option;
  47 val cgi_http_accept       : unit -> string option;
  48 val cgi_http_user_agent   : unit -> string option;
  49 val cgi_http_referer      : unit -> string option;
  50 val cgi_path_info         : unit -> string option;
  51 val cgi_path_translated   : unit -> string option;
  52 val cgi_script_name       : unit -> string option;
  53 val cgi_query_string      : unit -> string option;
  54 val cgi_remote_host       : unit -> string option;
  55 val cgi_remote_addr       : unit -> string option;
  56 val cgi_remote_user       : unit -> string option;
  57 val cgi_remote_ident      : unit -> string option;
  58 val cgi_auth_type         : unit -> string option;
  59 val cgi_content_type      : unit -> string option;
  60 val cgi_content_length    : unit -> string option;
  61 val cgi_annotation_server : unit -> string option;
  62
  63 end (* signature CGI *)
  64
  65 (* The Mosmlcgi library is for writing CGI programs in Moscow ML.  A
  66    CGI program may be installed on a WWW server and is invoked in
  67    response to HTTP requests sent to the server from a web browser,
  68    typically from an HTML FORM element.
  69
  70
  71    1. Obtaining field values sent from an ordinary HTML form
  72    ---------------------------------------------------------
  73
  74    [cgi_fieldnames] is a list of the names of fields present in the
  75    CGI call message.  If field name fnm is in cgi_fieldnames, then
  76    cgi_field_string fnm <> NONE.
  77
  78    [cgi_field_strings fnm] is a (possibly empty) list of the strings
  79    bound to field fnm.
  80
  81    [cgi_field_string fnm] returns SOME(s) where s is a string bound to
  82    field name fnm, if any; otherwise NONE.  Equivalent to
  83         case cgi_field_strings fnm of
  84              []     => NONE
  85            | s :: _ => SOME s
  86
  87    [cgi_field_integer (fnm, deflt)] attempts to parse an integer from
  88    field fnm.  Returns i if cgi_field_string(fnm) = SOME(s) and an
  89    integer i can be parsed from a prefix of s; otherwise returns deflt.
  90
  91
  92    2. Obtaining field values sent with ENCTYPE="multipart/form-data"
  93    -----------------------------------------------------------------
  94
  95    [cgi_partnames] is a list of the names of the parts of the
  96    multipart/form-data message.
  97
  98    The type part is the abstract type of parts of a message.  Each part
  99    may have several fields.  In this implementation, the field of a
 100    part cannot be a another part itself.
 101
 102    [cgi_parts pnm] is a (possibly empty) list of the parts called pnm.
 103
 104    [cgi_part pnm] is SOME(prt) where prt is a part called pnm, if any;
 105    otherwise NONE.  Equivalent to
 106         case cgi_parts pnm of
 107              []       => NONE
 108            | prt :: _ => SOME prt
 109
 110    [part_fieldnames prt] is the list of field names in part pnm.
 111
 112    [part_type prt] is SOME(typ) if the part prt contains a specification
 113    `Context-Type: typ'; otherwise NONE.
 114
 115    [part_data prt] is the data contain in part prt; for instance, the
 116    contents of a file uploaded via form-based file upload.
 117
 118    [part_field_strings prt fnm] is a (possibly empty) list of the
 119    strings bound to field fnm in part prt.
 120
 121    [part_field_string prt fnm] returns SOME(s) where s is a string
 122    bound to field name fnm in part prt, if any; otherwise NONE.
 123    Equivalent to
 124         case part_field_strings prt fnm of
 125              []     => NONE
 126            | s :: _ => SOME s
 127
 128    [part_field_integer prt (fnm, deflt)] attempts to parse an integer
 129    from field fnm of part prt.  Returns i if part_field_string prt fnm
 130    = SOME(s) and an integer i can be parsed from a prefix of s;
 131    otherwise returns deflt.
 132
 133
 134    3. Administrative and server information
 135    ----------------------------------------
 136
 137    Each of the following variables has the value SOME(s) if the
 138    corresponding CGI environment variable is bound to string s;
 139    otherwise NONE:
 140
 141    [cgi_server_software] is the value of SERVER_SOFTWARE
 142
 143    [cgi_server_name] is the value of SERVER_NAME
 144
 145    [cgi_gateway_interface] is the value of GATEWAY_INTERFACE
 146
 147    [cgi_server_protocol] is the value of SERVER_PROTOCOL
 148
 149    [cgi_server_port] is the value of SERVER_PORT
 150
 151    [cgi_request_method] is the value of REQUEST_METHOD
 152
 153    [cgi_http_accept] is the value of HTTP_ACCEPT
 154
 155    [cgi_http_user_agent] is the value of HTTP_USER_AGENT
 156
 157    [cgi_http_referer] is the value of HTTP_REFERER
 158
 159    [cgi_path_info] is the value of PATH_INFO
 160
 161    [cgi_path_translated] is the value of PATH_TRANSLATED
 162
 163    [cgi_script_name] is the value of SCRIPT_NAME
 164
 165    [cgi_query_string] is the value of QUERY_STRING
 166
 167    [cgi_remote_host] is the value of REMOTE_HOST
 168
 169    [cgi_remote_addr] is the value of REMOTE_ADDR
 170
 171    [cgi_remote_user] is the value of REMOTE_USER
 172
 173    [cgi_remote_ident] is the value of REMOTE_IDENT
 174
 175    [cgi_auth_type] is the value of AUTH_TYPE
 176
 177    [cgi_content_type] is the value of CONTENT_TYPE
 178
 179    [cgi_content_length] is the value of CONTENT_LENGTH, that is, the
 180    length of the data transmitted in the CGI call.
 181
 182    [cgi_annotation_server] is the value of ANNOTATION_SERVER
 183 *)