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;
or
&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.
|