Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Request(3)	      User Contributed Perl Documentation	    Request(3)

NAME
       APR::Request - wrapper for libapreq2's module/handle API.

SYNOPSIS
	 use APR::Request;

	 $req =	APR::Request::Custom->handle($pool,
					     "foo=arg1&bar=arg2",
					     "apache=quux",
					      $parser, 1e6, $bb);
	 $param	= $req->param("foo");
	 $cookie = $req->jar("apache");

DESCRIPTION
       The "APR::Request" module provides the base methods for interfacing
       with libapreq2's	module API.  It	also provides a	few utility functions
       and constants.

       This manpage documents version 2.13 of the APR::Request,
       APR::Request::Custom, APR::Request::Cookie::Table, and
       APR::Request::Param::Table packages.

METHODS
       APR::Request::Custom - derived from APR::Request.

   handle
	   APR::Request::Custom->handle($pool,
					$query_string,
					$cookie_header,
					$parser,
					$read_limit,
					$brigade)

       Creates a new APR::Request::Custom object.  The $query_string and
       $cookie_headers are immediately parsed into the "args" and "jar"
       tables.	The $parser is an APR::Request::Parser object which is invoked
       when fetching "body" entries from the $brigade.	The $read_limit
       represents the maximum number of	bytes this handle may feed into	the
       parser.

METHODS
       APR::Request

   pool
	   $req->pool()

       Returns the APR::Pool object associated to this handle.

   bucket_alloc
	   $req->bucket_alloc()

       Returns the APR::BucketAlloc object associated to this handle.

   jar_status
	   $req->jar_status()

       Returns the final status	code of	the handle's cookie header parser.

   args_status
	   $req->args_status()

       Returns the final status	code of	the handle's query-string parser.

   body_status
	   $req->body_status()

       Returns the final status	code of	the handle's body parser.

   param_status
	   $req->param_status()

       Returns "($req->args_status, $req->body_status)"	in list	context;
       otherwise returns "$req->args_status || $req->body_status".

   parse
	   $req->parse()

       Parses the jar, args, and body tables. Returns "$req->jar_status,
       $req->args_status, $req->body_status".

	   @status = $req->parse;
	   ok @status == 3;
	   ok $status[0] == $req->jar_status;
	   ok $status[1] == $req->args_status;
	   ok $status[2] == $req->body_status;

   jar
	   $req->jar()
	   $req->jar($key)

       With no arguments, this method returns a	tied
       APR::Request::Cookie::Table object (or undef if the "Cookie" header is
       absent) in scalar context, or the names (in order, with repetitions) of
       all the parsed cookies.

       With the	$key argument, in scalar context this method fetches the first
       matching	cookie.	 In list context it returns all	matching cookies.  The
       returned	cookies	are the	values as they appeared	in the incoming	Cookie
       header.

       jar() will throw	an APR::Request::Error object whenever jar_status() is
       non-zero	and the	return value is	potentially invalid (eg	"scalar
       $req->jar($key)"	will not die if	the desired cookie was successfully
       parsed).

	   $jar	= $req->jar;
	   @cookie_names = $req->jar;
	   ok $jar->isa("APR::Request::Cookie::Table");
	   ok shift @cookie_names eq $_	for keys %$jar;

	   $cookie = $req->jar("apache");
	   @cookies = $req->jar("apache");

   args
	   $req->args()
	   $req->args($key)

       With no arguments, this method returns a	tied
       APR::Request::Param::Table object (or undef if the query	string is
       absent) in scalar context, or the names (in order, with repetitions) of
       all the parsed query-string arguments.

       With the	$key argument, in scalar context this method fetches the first
       matching	query-string arg.  In list context it returns all matching
       args.

       args() will throw an APR::Request::Error	object whenever	args_status()
       is non-zero and the return value	is potentially invalid (eg "scalar
       $req->args($key)" will not die if the desired query argument was
       successfully parsed).

	  $args	= $req->args;
	  @arg_names = $req->args;
	  ok $args->isa("APR::Request::Param::Table");
	  ok shift @arg_names eq $_ for	keys %$args;

	  $foo = $req->args("foo");
	  @bar = $req->args("bar");

   body
	   $req->body()
	   $req->body($key)

       With no arguments, this method returns a	tied
       APR::Request::Param::Table object (or undef if the request body is
       absent) in scalar context, or the names (in order, with repetitions) of
       all the parsed cookies.

       With the	$key argument, in scalar context this method fetches the first
       matching	body param.  In	list context it	returns	all matching body
       params.

       body() will throw an APR::Request::Error	object whenever	body_status()
       is non-zero and the return value	is potentially invalid (eg "scalar
       $req->body($key)" will not die if the desired body param	was
       successfully parsed).

	   $body = $req->body;
	   @body_names = $req->body;
	   ok $body->isa("APR::Request::Param::Table");
	   ok shift @body_names	eq $_ for keys %$body;

	   $alpha = $req->body("alpha");
	   @beta = $req->body("beta");

   param
	   $req->param()
	   $req->param($key)

       With no arguments, this method returns a	tied
       APR::Request::Param::Table object (or undef, if the query string	and
       request body are	absent)	in scalar context, or the names	(in order,
       with repetitions) of all	the incoming (args + body) params.

       With the	$key argument, in scalar context this method fetches the first
       matching	param.	In list	context	it returns all matching	params.

       param() will throw an APR::Request::Error object	whenever
       param_status() is non-zero and the return value is potentially invalid
       (eg "scalar $req->param($key)" will not die if the desired param	was
       successfully parsed).

	   $param = $req->param;
	   @param_names	= $req->param;
	   ok $param->isa("APR::Request::Param::Table");
	   ok shift @param_names eq $_ for keys	%$param;

	   $foo	= $req->param("foo");
	   @foo	= $req->param("foo");

   upload
	   $req->upload()
	   $req->upload($key)

       With no arguments, this method returns a	tied
       APR::Request::Param::Table object (or undef if the request body is
       absent) in scalar context (whose	entries	are APR::Request::Param
       objects), or the	names (in order, with repetitions) of all the incoming
       uploads.

       With the	$key argument, in scalar context this method fetches the first
       matching	upload.	 In list context it returns all	matching uploads.  The
       return values are APR::Request::Param objects.

       upload()	will throw an APR::Request::Error object whenever
       body_status() is	non-zero.

	   $uploads = $req->upload;
	   @upload_names = $req->upload;
	   ok $uploads->isa("APR::Request::Param::Table");
	   ok shift @upload_names eq $_	for keys %$uploads;
	   ok $_->upload for values %$uploads;

	   $up = $req->upload("beta");
	   @ups	= $req->upload("beta");
	   ok $_->isa("APR::Request::Param") for $up, @ups;
	   ok $_->upload for $up, @ups;

   read_limit
	   $req->read_limit()
	   $req->read_limit($set)

       Get/set the read	limit, which controls the total	amount of bytes	that
       can be fed to the current parser.

   brigade_limit
	   $req->brigade_limit()
	   $req->brigade_limit($set)

       Get/set the brigade_limit for the current parser.  This limit
       determines how many bytes of a file upload that the parser may spool
       into main memory.  Uploads exceeding this limit are written directly to
       disk.

   temp_dir
	   $req->temp_dir()
	   $req->temp_dir($set)

       Get/set the spool directory for uploads which exceed the	configured
       brigade_limit.

   disable_uploads
	   $req->disable_uploads()

       Engage the disable_uploads hook for this	request.

   upload_hook
	   $req->upload_hook($callback)

       Add an upload hook callback for this request.  The arguments to the
       $callback sub are ($upload, $new_data).

   import
       Exports a list of subs into the caller's	package.

SUBROUTINES
       APR::Request

   encode
	   encode($string)

       Exportable sub which returns the	url-encoded form of $string.

   decode
	   decode($string)

       Exportable sub which returns the	url-decoded form of $string.

SUBCLASSING
       APR::Request

       If the instances	of your	subclass are hash references then you can
       actually	inherit	from APR::Request as long as the APR::Request object
       is stored in an attribute called	"r" or "_r". (The APR::Request class
       effectively does	the delegation for you automagically, as long as it
       knows where to find the APR::Request object to delegate to.)  For
       example:

	       package MySubClass;
	       use APR::Request::Custom;
	       our @ISA	= qw(APR::Request);
	       sub new {
		   my($class, @args) = @_;
		   return bless	{ r => APR::Request::Custom->handle(@args) }, $class;
	       }

METHODS
	 APR::Request::Cookie::Table - read-only version of APR::Table.

       Tables in this class normally arise from	calls to
       "APR::Request::jar()".

   cookie_class
	   $table->cookie_class()
	   $table->cookie_class($set)

       Get/set the class each table element is blessed into during a get or
       FETCH call.  If defined,	the class must be derived from
       APR::Request::Cookie.  When called with $set, it	returns	the $table.
       Otherwise it returns the	name of	the current class, or undef if no
       cookie class is defined.

   get
	   $table->get($key)

       Same as FETCH.

   FETCH
	   $table->FETCH($key)

       In scalar context, this returns the first value matching	$key (note:
       see NEXTKEY for additional notes).  The match is	always case-
       insensitive.  In	list context, this returns all matching	values.	 Note:
       the type	of the return values depends on	the table's current
       cookie_class.

   EXISTS
       Synonym for "defined"; these tables are not allowed to contain
       undefined values. Since these are constant tables, they don't
       autovivify either.

   FIRSTKEY
	   $table->FIRSTKEY()

       Returns the first key in	the table.

   NEXTKEY
	   $table->NEXTKEY()

       Returns the next	key in the table.  For perl 5.8+, if the key is
       multivalued, a subsequent FETCH on this key will	return the
       corresponding value, until either NEXTKEY or FIRSTKEY is	invoked	again.
       For perl	5.6, FETCH always returns the first value.

   do
	   $table->do($callback, @keys)

       Same as APR::Table::do; iterates	over the table calling
       $callback->($key, $value) for each matching @keys.  If @keys is empty,
       this iterates over the entire table.

       Note: The type of $value	inserted into the callback depends on the
       table's current cookie_class.

METHODS
       APR::Request::Param::Table

   param_class
	   $table->param_class()
	   $table->param_class($set)

       Get/set the class each table element is blessed into during a "get" or
       "FETCH" call.  If defined, the class must be derived from
       APR::Request::Param.  When called with $set, it returns the $table.
       Otherwise it returns the	name of	the current class, or undef if no
       param class is defined.

   get
	   $table->get($key)

       Same as FETCH.

   FETCH
	   $table->FETCH($key)

       In scalar context, this returns the first value matching	$key (see
       NEXTKEY for additional notes on this).  The match is always case-
       insensitive.  In	list context, this returns all matching	values.	 Note:
       the type	of the return values depends on	the table's current
       param_class.

   EXISTS
       Synonym for "defined"; these tables are not allowed to contain
       undefined values. Since these are constant tables, they don't
       autovivify either.

   NEXTKEY
	   $table->NEXTKEY()

       Returns the next	key in the table.  For perl 5.8+, if the key is
       multivalued, a subsequent FETCH on this key will	return the
       corresponding value, until either NEXTKEY or FIRSTKEY is	invoked	again.
       For perl	5.6, FETCH always returns the first value.

   FIRSTKEY
	   $table->FIRSTKEY()

       Returns the first key in	the table.

   do
	   $table->do($callback, @keys)

       Same as APR::Table::do; iterates	over the table calling
       $callback->($key, $value) for each matching @keys.  If @keys is empty,
       this iterates over the entire table.

       Note: The type of $value	inserted into the callback depends on the
       table's current value_class.

SEE ALSO
       APR::Request::Error, APR::Request::Param, APR::Request::Cookie,
       APR::Request::Parser

COPYRIGHT
	 Licensed to the Apache	Software Foundation (ASF) under	one or more
	 contributor license agreements.  See the NOTICE file distributed with
	 this work for additional information regarding	copyright ownership.
	 The ASF licenses this file to You under the Apache License, Version 2.0
	 (the "License"); you may not use this file except in compliance with
	 the License.  You may obtain a	copy of	the License at

	     http://www.apache.org/licenses/LICENSE-2.0

	 Unless	required by applicable law or agreed to	in writing, software
	 distributed under the License is distributed on an "AS	IS" BASIS,
	 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	 See the License for the specific language governing permissions and
	 limitations under the License.

perl v5.24.1			  2017-07-02			    Request(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | METHODS | SUBROUTINES | SUBCLASSING | METHODS | METHODS | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=APR::Request&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help