home *** CD-ROM | disk | FTP | other *** search
/ PC Online 1997 May / PCO_5_97.ISO / FilesBBS / OS2 / HYPEMAIL.ARJ / HYPEMAIL.ZIP / libcgi / libcgi.doc < prev    next >
Encoding:
Text File  |  1994-07-27  |  4.7 KB  |  201 lines
  1. There are two new data types in cgi.h (which must be #included in
  2. your program, presumably as lib/cgi.h):
  3.  
  4. typedef struct
  5. {
  6.   char *server_software;
  7.   char *server_name;
  8.   char *gateway_interface;
  9.   char *server_protocol;
  10.   char *server_port;
  11.   char *request_method;
  12.   char *http_accept;
  13.   char *path_info;
  14.   char *path_translated;
  15.   char *script_name;
  16.   char *query_string;
  17.   char *remote_host;
  18.   char *remote_addr;
  19.   char *auth_type;
  20.   char *remote_user;
  21.   char *remote_ident;
  22.   char *content_type;
  23.   int content_length;
  24. } cgi_info;
  25.  
  26. typedef struct festruct
  27. {
  28.   unsigned char *name;
  29.   unsigned char *val;
  30.   struct festruct *next;
  31. } form_entry;
  32.  
  33.  
  34. Here are the API functions that do relevant things:
  35.  
  36. SYNOPSIS
  37.   main()
  38.   cgi_main()
  39.  
  40. DESCRIPTION
  41.   libcgi contains a simple stub of a main program, which merely
  42.   calls cgi_main().  Thus cgi_main is actually the entry point for
  43.   your CGI-processing code.  It is this way to be upwardly-compatible
  44.   with linking in CGI programs to the server.  There will be name
  45.   conflicts with multiple cgi_main's, though.  We'll worry about it
  46.   later.
  47.  
  48. --------
  49.  
  50. SYNOPSIS
  51.   int get_cgi_info(cgi_info *)
  52.  
  53. DESCRIPTION
  54.   This routine paws through the environment and fills up the struct
  55.   provided, which must already be allocated.
  56.  
  57. RETURNS
  58.   zero if there is a problem.
  59.  
  60. --------
  61.  
  62. SYNOPSIS
  63.   form_entry *get_form_entries(cgi_info *)
  64.   void free_form_entries(cgi_info *)
  65.   char *parmval(form_entry *, char *)
  66.  
  67. DESCRIPTION
  68.   get_form_entries parses any form inputs information into a linked-list
  69.   of name/value pairs, returning the head pointer of that list.  It does
  70.   all plus-to-space and hex code translations.
  71.   
  72.   free_form_entries reclaims all the memory from the provided linked-list.
  73.  
  74.   parmval returns the value corresponding to the name in the second
  75.   argument (a caseless string compar) by a linear search through the list
  76.   in the first argument.
  77.  
  78. RETURNS
  79.   get_form_enties returns the head pointer, or NULL if there is a problem
  80.   or no form input information was available.
  81.  
  82.   parmval returns the corresponding value string or NULL if there is a
  83.   problem or no matching name.
  84.  
  85. --------------
  86.  
  87. SYNOPSIS
  88.   int syn_mimeheader(char *, char *)
  89.   int print_mimeheader(char *)
  90.  
  91. DESCRIPTION
  92.   syn_mimeheader creates a MIME header based on the MIME type in
  93.   the second string and writes it into the first string buffer
  94.   (including trailing double-newline).
  95.  
  96.   print_mimeheader creates the same MIME header based on the MIME
  97.   type in its sole argument, and prints it to stdout
  98.  
  99. RETURNS
  100.   both return 0 if there is a problem
  101.  
  102. -------------
  103.  
  104. SYNOPSIS
  105.   int syn_base_url(char *, cgi_info *)
  106.   int print_base_url(cgi_info *)
  107.  
  108. DESCRIPTION
  109.   syn_base_url reconstructs the virtual document's URL given the
  110.   cgi_info, minus any query string, and fills the provided char
  111.   buffer.
  112.  
  113.   print_base_url does the same but prints to stdout instead
  114.  
  115. RETURNS
  116.   both return 0 if there is a problem
  117.  
  118. --------------
  119.  
  120. SYNOPSIS
  121.   int mcode(cgi_info *)
  122.  
  123. DESCRIPTION
  124.   This function examines the request_method in the cgi information
  125.   and returns an integer code.  These codes are defined in cgi.h.
  126.  
  127. RETURNS
  128.   0 if it doesn't recognize the method name, otherwise the code as
  129.   defined in cgi.h
  130.  
  131. --------------
  132.  
  133. SYNOPSIS
  134.   char *trim(char *s)
  135.  
  136. DESCRIPTION
  137.   Changes the string from blank-padded to NULL-padded
  138.  
  139. RETURNS
  140.   its argument
  141.  
  142. --------------
  143.  
  144. SYNOPSIS
  145.   char *sanitize(char *to, char *from)
  146.  
  147. DESCRIPTION
  148.   Prepares the string for inclusion in a URL.  That is, the from
  149.   string is copied to the to buffer except that blanks are turned
  150.   into '+' characters and non-alphanumerics are turned into
  151.   3-character sequences of a '%' followed by two hex digits
  152.   corresponding to the ascii code.
  153.  
  154. RETURNS
  155.   the to string
  156.  
  157. --------------
  158.  
  159. SYNOPSIS
  160.   void print_sel_list(char *tname, char **opts, char *init)
  161.  
  162. DESCRIPTION
  163.   Prints an HTML+ selection list construct to stdout.  The name of
  164.   the SELECT tag is given by tname, and the NULL-terminated string
  165.   array opts is turned into separate OPTION tags with values
  166.   corresponding to entries in opts.  If any of these entries
  167.   are a caseless match with init, then that OPTION tag is the
  168.   default selection.
  169.  
  170. --------------
  171.  
  172. SYNOPSIS
  173.   void print_input_blank(char *tname, unsigned size, char *init)
  174.  
  175. DESCRIPTION
  176.   Prints an HTML+ INPUT tag (of type text) to stdout.  The tag's
  177.   name is tname, its size is size, and initial value is init.
  178.  
  179. --------------
  180.  
  181. SYNOPSIS
  182.   void print_submit(char *label)
  183.  
  184. DESCRIPTION
  185.   Prints an HTML+ INPUT tag of type submit to stdout.  The submit
  186.   button will be labelled by label if non-NULL.
  187.  
  188. --------------
  189.  
  190. SYNOPSIS
  191.   char *strmaxcpy(char *s1, char *s2, int n)
  192.  
  193. DESCRIPTION
  194.   copies at most n-1 characters from s2 into s1, and then
  195.   null-terminates.  Handy for truncating while copying.
  196.  
  197. RETURNS
  198.   s1 as long as n > 0, NULL otherwise
  199.  
  200. --------------
  201.