NAME

HandyCGI is a package that will aid you to implement code that interacts with web server via Common Gateway Interface. This module is compliant with requirements of FastCGI or such approach, and it is light-weight and fully functional as well.

Portability notes

flock should be supported by your platform. See perlport manual. Path separators is '/' which works well on UNIXes and Win32 platforms. If crypt (default) is used as encryption function in set_user_password subroutine, then it should be implemented in your platform.

Required packages

IO::Socket

If your perl distribution does not contain this function, just comment out use IO::Socket string at the beginning of the module and comment geturl whole function.

DB_File

Used to alter web server's authentification password lists in DB format. If your platform does not have this module, you could comment all lines within this file, that either contains 'DB_File' or 'tie' pattern. If you do this, please do not call &set_user_password with filetype equal to 'db'.

Compress::Zlib

Used to compress pages using gzip on the fly. If your platform does not have this module, then you should comment in this file all lines, which contain 'Compress::Zlib' pattern. Please, also set $cfg{'cgigzip'} to 0 in config.pm configuration file.

SYNOPSIS

use HandyCGI;
&cgi_start;
$hin{'this_var_come_from_query_string'};
$this_cookie_comes_from_browser = 
  &get_cookie('this_cookie_comes_from_browser');
&set_cookie('this_cookie_goes_to_browser',
  'hello - expires in 1 hour',time+3600);
&cgi_finish;

&cgi_finish("Content-Type: text/html"); 

# if you want to feed CGI headers
# explictly to web server.

CONFIGURATION

config.pm

We encourage you to store all your project configuration data in config module inside of hash %cfg. All configuration for HandyCGI, HandyTemplate, HandySQL, HandyLog, HandyMail and HandyList modules are stored in this file by default. However, if you dislike this approach feel free to modify code a little.

cgigzip

If set to 1, then gzip compression is used to compress data that is going to web browser (this is done only if web browser is capable to decompress gzip-compressed data). If set to 0, then automatic gzip compression is disabled. gzip compression is useful, if you'd like to make higher response-time to your web site clients, because usual HTML pages takes around 30 kilobytes, gzip will make HTML pages almost 10 times smaller - just imagine how this improves response time!

Default: 1

sfid_file

This is container file, which contains session information. &sfid; is really an offset in this file, where session data records are stored. Records are separated with \x01 character. CGI application should have read-write access to this file.

Default: tmp/sfid.txt

maxsfidsize

Maximum file size allowed for sfid_file. The more size allowed, more hits can be served. Usually hit will take around 200 bytes of disk space. So 1000000/200 = 5000 hits. If your server load is less than 5000 hits/hour, than it is enough (it guarantees that session will be stored for individual user at least for one hour).

Default: 1000000

maxdata

Maximum data allowed to receive from web browser in bytes. If you do not support uploads, 32768 (32 kb) will be probably enough, but if your site supports file uploads, then put here maximum file size that could be uploaded + 32 kb.

Default: 131072

auth_dir

Default directory where web server authentification password lists are stored.

Default: tmp/pw

DESCRIPTION

General behaviour

Module exports functions, that should be used to parse input from web server (done by subroutine cgi_start), get some variables in web server-independent manner, print data, and feed everything back to http server (subroutine cgi_finish). So calls to cgi_start and cgi_finish are mandatory.

cgi_start

Reads everything from server variables. If magic variable 'sfid' is not equal to 0 (or NA), then input data is read from so-called sfid-file, as well from query string (or POST request, this will not be repeated any more, but, of course, all request methods are supported - GET, POST and POST of multipart/form-data). If sfid-file is not present, than data is read only from query string. Parameters both from sfid-file and query string are loaded into %hin (input hash from web server - shortened name to increase usability). Parameters that are read only from sfid-file are read into %hl (input from previously saved sfid-file only). Also if request method is POST multipart/form-data, then %hinh of each element that is contained in %hin hash contains appropriate headers of each MIME part.

%hin has format $hin{'parameter_X'} eq 'value_of_parameter_X'. %hl has the same format as %hin.

%hinh has format $hinh{'parameter_X'}{'header_in_lowercase'} eq 'header_value'. The most interesting header element for you in case of file uploads will be 'content-disposition'. See CGI reference to understand what headers are available for POST multipart/form-data request.

cgi_finish

Prints output to web server. Saves 'sfid' magic file (if required). Data from special hashes %hout and %hs are saved. %hout contains parameters that are saved into sfid-file, but will be redefinable by input query string at next call to the cgi_start. %hs should be used to save ``sticky'' parameters - they will overload any input query string parameters in next call to cgi_start.

Also this function performs the following substitutions:

&sfid;	=>	number of sfid file
&lbr;	=>	{
&rbr;	=>	}
&baseurl;	=>	URL to your script without current query string e.g. http://domain/path/to/script/script.cgi
&realurl;	=>	URL to your web server without ending slash e.g. http://domain

If you want to feed specific headers to web server (or change content-type) do the following:

&cgi_finish(``Content-Type: text/html'');

or more complex example:

&cgi_finish(``Location: http://test/\nContent-Type: text/html'');

cgi_jump_to ($url)

All requests to current script will be redirected to $url.

e.g. &cgi_jump_to('http://www.perl4you.com/');

All requests to current script will be redirected to www.perl4you.com.

get_user_name

If you have configured your web server to support Basic or Digest user authentification, then for secured areas this function will return authentificated user name.

set_user_password

This function could be used out-of-box to control Basic or Digest authentification password lists of web server.

Two call possibilities:

&set_user_password($filename,$filetype, $username,$password,$encfunc) will make sure that user $username with password
$password exists. If $encfunc contains reference to subroutine, then it will be used for password encryption instead of standard crypt. This subroutine has exactly one argument - unencrypted password. It should return encrypted password.
set_user_password($filename,$filetype,$username) will effectively disable user $username from logging into restricted area.
$filetype eq 'userfile' file with username:password.

  e.g.
  test:ASDFSDLJGKSDT
  root:ASDFLKASDJFKL

$filetype eq 'db' file is a Berkley DB with username:password.
$filename is absolute file name or relative to
$cfg{'auth_dir'} directory.

geturl ($url)

Performs HTTP/1.1 GET request to URL $url. Returns fetched data with HTTP headers. undef is returned if call was unsuccessful. Extremly light-weight function.

posturl ($url, $data)

Performs HTTP/1.1 POST request to URL $url. $data is a hash that contains parameters that will be feed to requested URL. Returns fetched data with HTTP headers. undef is returned if call was unsuccessful. Extremly light-weight function.

get_user_agent

Returns 'IE4' if browser is 'Internet Explorer 4.0', 'IE5' - for 'Internet Explorer 5.0', 'NN4' if browser is 'Netscape Navigator 4.x' and '' if undetermined. It could be used to determine what kind of JavaScript/DHTML could be sent to browser.

get_request_method

Returns 'GET' or 'POST'.

get_server_name

Returns name of the server. e.g. host.domain

get_base_URL_wo_script

Returns URL without script filename. e.g. http://host.domain

get_base_URL

Returns URL with script name (but without query string). e.g. http://domain/path/to/script/script.cgi

get_full_URL

Returns URL with script name and query string. e.g. http://domain/path/to/script/script.cgi/path_info?query

get_http_referer

Returns URL, from which we come to this script.

get_path_info

Returns path info. Look closer at this URL: http://domain/path/to/script/script.cgi/path_info?query

query is the query string, but path_info is the part of URL that is returned by calling of this function. Useful to load templates, for example.

get_remote_addr

Retrieves remote address if connection was established without proxy. Or the whole trace of addresses, if connection was established through proxy. First element of retrieved list is always the farmost point of the trace. Last element is the proxy that has actually requested page. In scalar context returns first element of retrieved chain. In array context returns whole proxy trace chain.

print_html (@)

Prints data to web server. Interface is similar to print.

printf_html (@)

Prints data to web server, but interface is similar to printf.

print_html_hash ($)

Equivalent of print_html(make_html_hash($)).

make_html_hash ($hashref)

Returns HTML code, that represents data in %$hashref. Useful for debugging or other dirty hash printing.

delete_cookie ($key)

Removes cookie, referred by key.

get_cookie ($key)

Returns value of cookie, referred by key.

set_cookie ($key,$value,$expires,$domain,$path)

Sets $value to a cookie, referred by $key. $expires is the time (local here) of expiration. $domain is domain, for which cookie is applied (it will be returned to us in next call, only if domain name to script matches this one), $path - is relative path (that will trigger return of cookie). Mandatory are only $key, $value, $expires. Other are optional. If you do not know what is a cookie - just serf the web a little. This information is easy to locate.

$unescaped = unescape($escaped)

If $escaped is something like '+Some+Text+%2F+X', then $unescaped is ' Some Text = X'. Useful for encoding/decoding so-called URL-encoded strings. URL-encoded string is the type of encoding, that is used in URL notation.

$escaped = escape($unescaped)

Reverse of unescape.

&ip_to_int

&ip_to_int(``192.168.14.1'') returns integer representation of IP address 192.168.14.1

&ip_to_int(192,168,14,1) is the same call.

&int_to_ip

Converts integer representation, that is returned by &ip_to_int to string notation of IP address.

$htmlized = htmlize($not_htmlized)

``Htmlizes'' text. E.g. eliminates '<','>' and '&' from there. Don't feed HTML CODE into it!!! Also replaces '{' to &lbr; and '}' to &rbr;, which later is replaced by &cgi_finish to '{' and '}'. (this was implemented for templates, where '{' and '}' are reserved for internal use).

%hin, %hout, %hl, %hs - who are they ? How does session files work ?

%hin, %hl are loaded with parameters from CGI and session file. They are filled after cgi_start has been called. %hout, %hs are parameters that will be saved by cgi_finish subroutine into session file for subsequent calls of script.

To understand this mechanism, examine two launches of our test CGI script:

index.cgi?var1=1;var3=2

after CGI-start, you will have $hin{'var1'} eq '1' and $hin{'var3'} eq '2', $hl{'var1'} is undef and $hl{'var3'} is undef. Suppose, that in this launch, following sequence of code was executed:

$hout{'var1'} = 'out_var1'; $hout{'var2'} = 'out_var2'; $hs{'var3'} = 'saved_var3'; $hs{'var4'} = 'saved_var4';

In &cgi_finish next session file identifier (&sfid;) became, for example, 12. Here's what we'll get on the next launch:

index.cgi?sfid=12;var1=3;var3=4;

$hin{'var1'} eq '3' (Was overloaded by var1=3) $hin{'var2'} eq 'out_var2'
$hin{'var3'} eq 'saved_var3' (Overload DENIED) $hin{'var4'} eq 'saved_var4'

$hl{'var1'} eq 'out_var1' (No overloads at all, only saved data)
$hl{'var2'} eq 'out_var2' $hl{'var3'} eq 'saved_var3' $hl{'var4'} eq 'saved_var4'

Remember, that you should always pass to next script call &sfid; identifier, if you would like to use %hout or %hs. Sessions are secured, so only the same remote client is able to read session files, that left by previous calls to CGI scripts. Session security is granted by IP address backtrace.