home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / tsw / TSW_3.4.0.exe / Apache2 / perl / Request.pod < prev    next >
Encoding:
Text File  |  2004-02-15  |  7.2 KB  |  265 lines
  1. =head1 NAME
  2.  
  3. Apache::Request - Methods for dealing with client request data
  4.  
  5. =head1 SYNOPSIS
  6.  
  7.     use Apache::Request;
  8.     my $req = Apache::Request->new($r);
  9.  
  10. =head1 DESCRIPTION
  11.  
  12. I<Apache::Request> adds methods for parsing B<GET> requests and B<POST> 
  13. requests where I<Content-type> is one of I<application/x-www-form-urlencoded> or 
  14. I<multipart/form-data>.
  15.  
  16. =head1 Apache::Request METHODS
  17.  
  18. The interface is designed to mimic CGI.pm 's routines for parsing
  19. query parameters. The main differences are 
  20.  
  21. =over 4
  22.  
  23. =item * C<Apache::Request::new> takes an environment-specific
  24. object as (second) argument.
  25.  
  26. =item * The query parameters are stored as Apache::Table objects,
  27. and are therefore parsed using case-insensitive keys.
  28.  
  29. =item * The query string is always parsed, even for POST requests.
  30.  
  31. =back
  32.  
  33. =head2 new  
  34.  
  35. creates a new I<Apache::Request> object with an environment object $r:
  36.  
  37.     my $req = Apache::Request->new($r);
  38.  
  39. With mod_perl2, the environment object must be an I<Apache::RequestRec>
  40. object.  All methods from the environment class are inherited.
  41.  
  42. The following attributes are optional:
  43.  
  44. =over 4
  45.  
  46. =item POST_MAX
  47.  
  48. Limit the size of POST data (in bytes).
  49.  
  50. =item DISABLE_UPLOADS
  51.  
  52. Disable file uploads.
  53.  
  54. =item TEMP_DIR
  55.  
  56. Sets the directory where upload files are spooled.  On a *nix-like
  57. that supports link(2), the TEMP_DIR should be located on the same
  58. file system as the final destination file:
  59.  
  60.  my $req = Apache::Request->new($r, TEMP_DIR => "/home/httpd/tmp");
  61.  my $upload = $req->upload('file');
  62.  $upload->link("/home/user/myfile") || warn "link failed: $!";
  63.  
  64. =item HOOK_DATA [TODO]
  65.  
  66. Extra configuration info passed to an upload hook.
  67. See the description for the next item, I<UPLOAD_HOOK>.
  68.  
  69. =item UPLOAD_HOOK [TODO]
  70.  
  71. Sets up a callback to run whenever file upload data is read. This
  72. can be used to provide an upload progress meter during file uploads.
  73. Apache will automatically continue writing the original data to
  74. $upload->fh after the hook exits.
  75.  
  76.  my $transparent_hook = sub {
  77.    my ($upload, $buf, $len, $hook_data) = @_;
  78.    warn "$hook_data: got $len bytes for " . $upload->name;
  79.  };
  80.  
  81.  my $apr = Apache::Request->new($r, 
  82.                                 HOOK_DATA => "Note",
  83.                                 UPLOAD_HOOK => $transparent_hook,
  84.                                );
  85.  
  86. =back
  87.  
  88. =head2 instance
  89.  
  90. The default (and only) behavior of I<Apache::Request> is to intelligently
  91. cache B<POST> data for the duration of the request.  Thus there is no longer
  92. the need for a separate C<instance()> method as existed in I<Apache::Request>
  93. for Apache 1.3 - all B<POST> data is always available from each and every 
  94. I<Apache::Request> object created during the request's lifetime.
  95.  
  96. If you need an C<instance()> method to make ease the pains of porting to
  97. Apache 2.0, you can add this shortcut to your C<startup.pl>:
  98.  
  99.     use Apache::Request;
  100.     *Apache::Request::instance = \&Apache::Request::new;
  101.  
  102. =head2 param
  103.  
  104. Get or set (TODO) the request parameters (using case-insensitive keys) by
  105. mimicing the OO interface of C<CGI::param>.
  106.  
  107.     # similar to CGI.pm
  108.  
  109.     my $value = $req->param('foo');
  110.     my @values = $req->param('foo');
  111.     my @params = $req->param;
  112.  
  113.     # the following differ slightly from CGI.pm
  114.  
  115.     # assigns multiple values to 'foo'
  116.     $req->param('foo' => [qw(one two three)]); # TODO
  117.  
  118.     # returns ref to underlying apache table object
  119.     my $table = $req->param; # identical to $apr->parms - see below
  120.  
  121. =head2 parms, params
  122.  
  123. Get the full parameter table of the I<Apache::Request> object.
  124.  
  125.    # returns ref to Apache::Request::Table object provided by $apache_table
  126.    my $table = $req->parms;
  127.  
  128. An optional name parameter can be passed to return the parameter
  129. associated with the given name:
  130.  
  131.    my $param = $req->parms($name);
  132.  
  133. =head2 args
  134.  
  135. Returns an I<Apache::Request::Table> object containing the query-string 
  136. parameters of the I<Apache::Request> object.
  137.  
  138.    my $args = $req->args;
  139.  
  140. An optional name parameter can be passed to return the query string
  141. parameter associated with the given name:
  142.  
  143.    my $arg = $req->args($name);
  144.  
  145. =head2 body
  146.  
  147. Returns an I<Apache::Request::Table> object containing the POST data 
  148. parameters of the I<Apache::Request> object.
  149.  
  150.    my $body = $req->body;
  151.  
  152. An optional name parameter can be passed to return the POST data
  153. parameter associated with the given name:
  154.  
  155.    my $param = $req->body($name);
  156.  
  157.  
  158. =head2 upload
  159.  
  160. With no arguments, this returns an I<Apache::Upload::Table> object in 
  161. scalar context, or the names of all I<Apache::Upload> objects in
  162. list context.
  163.  
  164. An optional name parameter can be passed to return the I<Apache::Upload>
  165. object associated with the given name:
  166.  
  167.     my $upload = $apr->upload($name);
  168.  
  169. =head1 SUBCLASSING Apache::Request
  170.  
  171. If the instances of your subclass are hash references then you can actually
  172. inherit from Apache::Request as long as the Apache::Request object is stored in
  173. an attribute called "r" or "_r". (The Apache::Request class effectively does the
  174. delegation for you automagically, as long as it knows where to find the
  175. Apache::Request object to delegate to.)  For example:
  176.  
  177.     package MySubClass;
  178.     use Apache::Request;
  179.     our @ISA = qw(Apache::Request);
  180.     sub new {
  181.         my($class, @args) = @_;
  182.         return bless { r => Apache::Request->new(@args) }, $class;
  183.     }
  184.  
  185. =head1 Apache::Upload METHODS
  186.  
  187. =head2 name
  188.  
  189. The name of the filefield parameter:
  190.  
  191.     my $name = $upload->name;
  192.  
  193. =head2 filename
  194.  
  195. The filename of the uploaded file:
  196.  
  197.     my $filename = $upload->filename;
  198.  
  199. =head2 bb [replaces fh]
  200.  
  201. The APR::Brigade containing the contents of the uploaded file.
  202.  
  203. =head2 size [TODO]
  204.  
  205. The size of the file in bytes:
  206.  
  207.     my $size = $upload->size;
  208.  
  209. =head2 info
  210.  
  211. The additional header information for the uploaded file.
  212. Returns a hash reference tied to the I<Apache::Table> class.
  213. An optional I<key> argument can be passed to return the value of 
  214. a given header rather than a hash reference.  Examples:
  215.  
  216.     my $info = $upload->info;
  217.     while (my($key, $val) = each %$info) {
  218.     ...
  219.     }
  220.  
  221.     my $val = $upload->info("Content-type");
  222.  
  223. =head2 type [TODO]
  224.  
  225. Returns the I<Content-Type> for the given I<Apache::Upload> object:
  226.  
  227.     my $type = $upload->type;
  228.     #same as
  229.     my $type = $upload->info("Content-Type");
  230.  
  231. =head2 tempname [XXX- Does this mesh with brigade API?]
  232.  
  233. Provides the name of the spool file. This method is reserved for
  234. debugging purposes, and is possibly subject to change in a future
  235. version of Apache::Request.
  236.  
  237. =head2 link
  238.  
  239. To avoid recopying the upload's internal tempfile brigade on a 
  240. *nix-like system, I<link> will create a hard link to it:
  241.  
  242.   my $upload = $apr->upload('file');
  243.   $upload->link("/path/to/newfile") or
  244.       die sprintf "link from '%s' failed: $!", $upload->tempname;
  245.  
  246. Typically the new name must lie on the same file system as the
  247. brigade's tempfile. Check your system's link(2) manpage for details.
  248.  
  249. =head1 SEE ALSO
  250.  
  251. APR::Table(3)
  252.  
  253. =head1 CREDITS
  254.  
  255. This interface is based on the original pure Perl version by Lincoln Stein.
  256.  
  257. =head1 AUTHORS
  258.  
  259. Doug MacEachern, Joe Schaefer, Steve Hay.
  260.  
  261. =head1 MISSING DOCS
  262.  
  263. $req->config, Apache::Request::Table, Apache::Upload::Table.
  264.  
  265.