1=head1 NAME 2 3APR::Request - wrapper for libapreq2's module/handle API. 4 5 6=begin testing 7 use APR::Pool; 8 use APR::Brigade; 9 use APR::Bucket; 10 use APR::BucketAlloc; 11 use APR::Request; 12 use APR::Request::Parser; 13 $pool = APR::Pool->new; 14 $ba = APR::BucketAlloc->new($pool); 15 $bb = APR::Brigade->new($pool, $ba); 16 $content = <<EOT; 17---XYZ- 18Content-Disposition: form-data; name="alpha" 19Content-Type: text/plain; charset=us-ascii 20 21body1 22---XYZ- 23Content-Disposition: form-data; name="beta" filename="foo.txt" 24Content-Type: text/plain; charset=us-ascii 25 26body2 27---XYZ- 28Content-Disposition: form-data; name="foo" 29Content-Type: text/plain; charset=us-ascii 30 31body3 32---XYZ--- 33EOT 34 s/(?<!\015)\012/\015\012/g for $content; 35 $bb->insert_tail(APR::Bucket->new($ba, $content)); 36 $parser = APR::Request::Parser->multipart($pool, $ba, 37 "multipart/form-data; boundary=-XYZ-"); 38 39=end testing 40 41 42 43 44=head1 SYNOPSIS 45 46 47=for example begin 48 49 use APR::Request; 50 51 $req = APR::Request::Custom->handle($pool, 52 "foo=arg1&bar=arg2", 53 "apache=quux", 54 $parser, 1e6, $bb); 55 $param = $req->param("foo"); 56 $cookie = $req->jar("apache"); 57 58=for example end 59 60=for example_testing 61 ok $req->isa("APR::Request"); 62 is $param, "arg1", "param"; 63 is $cookie, "quux", "cookie"; 64 65 66=head1 DESCRIPTION 67 68The C<< APR::Request >> module provides the base methods 69for interfacing with libapreq2's module API. It also provides 70a few utility functions and constants. 71 72This manpage documents version 2.13 73of the APR::Request, APR::Request::Custom, 74APR::Request::Cookie::Table, and 75APR::Request::Param::Table packages. 76 77 78 79=head1 METHODS 80 81APR::Request::Custom - derived from APR::Request. 82 83 84 85 86=head2 handle 87 88 APR::Request::Custom->handle($pool, 89 $query_string, 90 $cookie_header, 91 $parser, 92 $read_limit, 93 $brigade) 94 95Creates a new APR::Request::Custom object. The $query_string 96and $cookie_headers are immediately parsed into the C<args> and 97C<jar> tables. The $parser is an APR::Request::Parser object 98which is invoked when fetching C<body> entries from the $brigade. 99The $read_limit represents the maximum number of bytes this handle 100may feed into the parser. 101 102 103 104 105 106=head1 METHODS 107 108APR::Request 109 110 111 112 113=head2 pool 114 115 $req->pool() 116 117Returns the APR::Pool object associated to this handle. 118 119=for example begin 120 121=for example end 122 123=for example_testing 124 is ${$req->pool()}, $$pool, "pool"; 125 126 127 128 129=head2 bucket_alloc 130 131 $req->bucket_alloc() 132 133Returns the APR::BucketAlloc object associated to this handle. 134 135=for example begin 136 137=for example end 138 139=for example_testing 140 is ${$req->bucket_alloc()}, $$ba, "bucket alloc"; 141 142 143 144 145=head2 jar_status 146 147 $req->jar_status() 148 149Returns the final status code of the handle's cookie header parser. 150 151=for example begin 152 153=for example end 154 155=for example_testing 156 is $req->jar_status == 0, 1, "jar status"; 157 158 159 160 161=head2 args_status 162 163 $req->args_status() 164 165Returns the final status code of the handle's query-string parser. 166 167=for example begin 168 169=for example end 170 171=for example_testing 172 is $req->args_status == 0, 1, "args status"; 173 174 175 176 177=head2 body_status 178 179 $req->body_status() 180 181Returns the final status code of the handle's body parser. 182 183=for example begin 184 185=for example end 186 187=for example_testing 188 is $req->body_status == 0, 1, "body status"; 189 190 191 192 193=head2 param_status 194 195 $req->param_status() 196 197Returns C<< ($req->args_status, $req->body_status) >> in list 198context; otherwise returns C<< $req->args_status || $req->body_status >>. 199 200=for example begin 201 202=for example end 203 204=for example_testing 205 is $req->param_status == 0, 1, "param status"; 206 207 208 209 210=head2 parse 211 212 $req->parse() 213 214Parses the jar, args, and body tables. Returns 215C<< $req->jar_status, $req->args_status, $req->body_status >>. 216 217=for example begin 218 219 @status = $req->parse; 220 ok @status == 3; 221 ok $status[0] == $req->jar_status; 222 ok $status[1] == $req->args_status; 223 ok $status[2] == $req->body_status; 224 225=for example end 226 227=for example_testing 228 $_ += 0 for @status; # convert to proper IVs 229 is "@status", "0 0 0", "parse"; 230 231 232 233 234=head2 jar 235 236 $req->jar() 237 $req->jar($key) 238 239With no arguments, this method returns a tied APR::Request::Cookie::Table 240object (or undef if the "Cookie" header is absent) in scalar context, or 241the names (in order, with repetitions) of all the parsed cookies. 242 243With the C<$key> argument, in scalar context this method fetches the first 244matching cookie. In list context it returns all matching cookies. 245The returned cookies are the values as they appeared in the incoming 246Cookie header. 247 248jar() will throw an APR::Request::Error object whenever jar_status() 249is non-zero and the return value is potentially invalid (eg 250C<< scalar $req->jar($key) >> will not die if the desired cookie 251was successfully parsed). 252 253 254=for example begin 255 256 $jar = $req->jar; 257 @cookie_names = $req->jar; 258 ok $jar->isa("APR::Request::Cookie::Table"); 259 ok shift @cookie_names eq $_ for keys %$jar; 260 261 $cookie = $req->jar("apache"); 262 @cookies = $req->jar("apache"); 263 264=for example end 265 266=for example_testing 267 is $cookie, "quux", "cookie"; 268 is "@cookies", "quux", "cookies"; 269 270 271 272 273=head2 args 274 275 $req->args() 276 $req->args($key) 277 278With no arguments, this method returns a tied APR::Request::Param::Table 279object (or undef if the query string is absent) in scalar context, or the 280names (in order, with repetitions) of all the parsed query-string arguments. 281 282With the C<$key> argument, in scalar context this method fetches the first 283matching query-string arg. In list context it returns all matching args. 284 285args() will throw an APR::Request::Error object whenever args_status() 286is non-zero and the return value is potentially invalid (eg 287C<< scalar $req->args($key) >> will not die if the desired query argument 288was successfully parsed). 289 290=for example begin 291 292 $args = $req->args; 293 @arg_names = $req->args; 294 ok $args->isa("APR::Request::Param::Table"); 295 ok shift @arg_names eq $_ for keys %$args; 296 297 $foo = $req->args("foo"); 298 @bar = $req->args("bar"); 299 300=for example end 301 302=for example_testing 303 is $foo, "arg1", "arg"; 304 is "@bar", "arg2", "args"; 305 306 307 308 309=head2 body 310 311 $req->body() 312 $req->body($key) 313 314With no arguments, this method returns a tied APR::Request::Param::Table 315object (or undef if the request body is absent) in scalar context, or the 316names (in order, with repetitions) of all the parsed cookies. 317 318With the C<$key> argument, in scalar context this method fetches the first 319matching body param. In list context it returns all matching body params. 320 321body() will throw an APR::Request::Error object whenever body_status() 322is non-zero and the return value is potentially invalid (eg 323C<< scalar $req->body($key) >> will not die if the desired body param was 324successfully parsed). 325 326=for example begin 327 328 $body = $req->body; 329 @body_names = $req->body; 330 ok $body->isa("APR::Request::Param::Table"); 331 ok shift @body_names eq $_ for keys %$body; 332 333 $alpha = $req->body("alpha"); 334 @beta = $req->body("beta"); 335 336=for example end 337 338=for example_testing 339 is $alpha, "body1", "alpha body"; 340 is "@beta", "foo.txt", "beta body"; 341 342 343 344 345=head2 param 346 347 $req->param() 348 $req->param($key) 349 350With no arguments, this method returns a tied APR::Request::Param::Table 351object (or undef, if the query string and request body are absent) in scalar 352context, or the names (in order, with repetitions) of all the incoming 353(args + body) params. 354 355With the C<$key> argument, in scalar context this method fetches the first 356matching param. In list context it returns all matching params. 357 358param() will throw an APR::Request::Error object whenever param_status() 359is non-zero and the return value is potentially invalid (eg 360C<< scalar $req->param($key) >> will not die if the desired param 361was successfully parsed). 362 363=for example begin 364 365 $param = $req->param; 366 @param_names = $req->param; 367 ok $param->isa("APR::Request::Param::Table"); 368 ok shift @param_names eq $_ for keys %$param; 369 370 $foo = $req->param("foo"); 371 @foo = $req->param("foo"); 372 373=for example end 374 375=for example_testing 376 is $foo, "arg1", "scalar param"; 377 is "@foo", "arg1 body3", "list param"; 378 379 380 381 382=head2 upload 383 384 $req->upload() 385 $req->upload($key) 386 387With no arguments, this method returns a tied APR::Request::Param::Table 388object (or undef if the request body is absent) in scalar context (whose 389entries are APR::Request::Param objects), or the names (in order, with 390repetitions) of all the incoming uploads. 391 392With the C<$key> argument, in scalar context this method fetches the first 393matching upload. In list context it returns all matching uploads. The return 394values are APR::Request::Param objects. 395 396upload() will throw an APR::Request::Error object whenever body_status() 397is non-zero. 398 399 400=for example begin 401 402 $uploads = $req->upload; 403 @upload_names = $req->upload; 404 ok $uploads->isa("APR::Request::Param::Table"); 405 ok shift @upload_names eq $_ for keys %$uploads; 406 ok $_->upload for values %$uploads; 407 408 $up = $req->upload("beta"); 409 @ups = $req->upload("beta"); 410 ok $_->isa("APR::Request::Param") for $up, @ups; 411 ok $_->upload for $up, @ups; 412 413 414=for example end 415 416=for example_testing 417 is $up, "foo.txt", "scalar upload"; 418 is "@ups", "foo.txt", "list upload"; 419 420 421 422 423=head2 read_limit 424 425 $req->read_limit() 426 $req->read_limit($set) 427 428 429Get/set the read limit, which controls the total amount of 430bytes that can be fed to the current parser. 431 432 433 434 435=head2 brigade_limit 436 437 $req->brigade_limit() 438 $req->brigade_limit($set) 439 440Get/set the brigade_limit for the current parser. This limit 441determines how many bytes of a file upload that the parser may 442spool into main memory. Uploads exceeding this limit are written 443directly to disk. 444 445 446=head2 temp_dir 447 448 $req->temp_dir() 449 $req->temp_dir($set) 450 451Get/set the spool directory for uploads which exceed the configured 452brigade_limit. 453 454 455=head2 disable_uploads 456 457 $req->disable_uploads() 458 459Engage the disable_uploads hook for this request. 460 461 462 463 464=head2 upload_hook 465 466 $req->upload_hook($callback) 467 468Add an upload hook callback for this request. The 469arguments to the $callback sub are ($upload, $new_data). 470 471 472 473 474=head2 import 475 476Exports a list of subs into the caller's package. 477 478 479 480 481=head1 SUBROUTINES 482 483APR::Request 484 485 486 487 488=head2 encode 489 490 encode($string) 491 492Exportable sub which returns the url-encoded form of C<$string>. 493 494 495 496 497=head2 decode 498 499 decode($string) 500 501Exportable sub which returns the url-decoded form of C<$string>. 502 503 504 505 506=head1 SUBCLASSING 507 508APR::Request 509 510If the instances of your subclass are hash references then you can actually 511inherit from APR::Request as long as the APR::Request object is stored in 512an attribute called "r" or "_r". (The APR::Request class effectively does the 513delegation for you automagically, as long as it knows where to find the 514APR::Request object to delegate to.) For example: 515 516 package MySubClass; 517 use APR::Request::Custom; 518 our @ISA = qw(APR::Request); 519 sub new { 520 my($class, @args) = @_; 521 return bless { r => APR::Request::Custom->handle(@args) }, $class; 522 } 523 524 525 526 527 528=head1 METHODS 529 530 APR::Request::Cookie::Table - read-only version of APR::Table. 531 532Tables in this class normally arise from calls to 533C<< APR::Request::jar() >>. 534 535 536 537 538=head2 cookie_class 539 540 $table->cookie_class() 541 $table->cookie_class($set) 542 543Get/set the class each table element is blessed into during a 544L<get> or L<FETCH> call. If defined, the class must be derived 545from APR::Request::Cookie. When called with $set, it returns 546the $table. Otherwise it returns the name of the current class, 547or undef if no cookie class is defined. 548 549 550 551=for example begin 552 $jar = $req->jar; 553 { 554 package FOO; 555 use base 'APR::Request::Cookie'; 556 } 557 $jar->cookie_class("FOO"); 558 ok $_->isa("FOO") for values %$jar; 559 560=for example end 561 562=for example_testing 563 $jar->do(sub { ok $_[1]->isa("FOO"); }); 564 565 566 567 568=head2 get 569 570 $table->get($key) 571 572Same as FETCH. 573 574 575 576=head2 FETCH 577 578 $table->FETCH($key) 579 580In scalar context, this returns the first value matching 581$key (note: see NEXTKEY for additional notes). The match 582is always case-insensitive. In list context, this returns 583all matching values. Note: the type of the return values 584depends on the table's current cookie_class. 585 586 587 588 589=head2 EXISTS 590 591Synonym for C<< defined >>; these tables are not 592allowed to contain undefined values. Since these 593are constant tables, they don't autovivify either. 594 595 596 597 598=head2 FIRSTKEY 599 600 $table->FIRSTKEY() 601 602Returns the first key in the table. 603 604 605 606 607=head2 NEXTKEY 608 609 $table->NEXTKEY() 610 611Returns the next key in the table. For perl 5.8+, 612if the key is multivalued, a subsequent FETCH on 613this key will return the corresponding value, until 614either NEXTKEY or FIRSTKEY is invoked again. For 615perl 5.6, FETCH always returns the first value. 616 617 618 619 620=head2 do 621 622 $table->do($callback, @keys) 623 624Same as APR::Table::do; iterates over the table 625calling $callback->($key, $value) for each matching 626@keys. If @keys is empty, this iterates over the 627entire table. 628 629Note: The type of $value inserted into the callback 630depends on the table's current cookie_class. 631 632 633 634 635=head1 METHODS 636 637APR::Request::Param::Table 638 639 640 641 642=head2 param_class 643 644 $table->param_class() 645 $table->param_class($set) 646 647 648Get/set the class each table element is blessed into during a 649C<get> or C<FETCH> call. If defined, the class must be derived 650from APR::Request::Param. When called with $set, it returns 651the $table. Otherwise it returns the name of the current class, 652or undef if no param class is defined. 653 654=for example begin 655 $body = $req->body; 656 { 657 package BAR; 658 use base 'APR::Request::Param'; 659 } 660 $body->param_class("BAR"); 661 ok $_->isa("BAR") for values %$body; 662 663=for example end 664 665=for example_testing 666 $body->do(sub { ok $_[1]->isa("BAR"); }); 667 668 669 670 671=head2 get 672 673 $table->get($key) 674 675Same as FETCH. 676 677 678 679 680=head2 FETCH 681 682 $table->FETCH($key) 683 684In scalar context, this returns the first value matching 685$key (see NEXTKEY for additional notes on this). The match 686is always case-insensitive. In list context, this returns 687all matching values. Note: the type of the return values 688depends on the table's current param_class. 689 690 691 692=head2 EXISTS 693 694Synonym for C<< defined >>; these tables are not 695allowed to contain undefined values. Since these 696are constant tables, they don't autovivify either. 697 698 699 700 701=head2 NEXTKEY 702 703 $table->NEXTKEY() 704 705Returns the next key in the table. For perl 5.8+, 706if the key is multivalued, a subsequent FETCH on 707this key will return the corresponding value, until 708either NEXTKEY or FIRSTKEY is invoked again. For 709perl 5.6, FETCH always returns the first value. 710 711 712 713 714=head2 FIRSTKEY 715 716 $table->FIRSTKEY() 717 718Returns the first key in the table. 719 720 721 722 723=head2 do 724 725 $table->do($callback, @keys) 726 727Same as APR::Table::do; iterates over the table 728calling $callback->($key, $value) for each matching 729@keys. If @keys is empty, this iterates over the 730entire table. 731 732Note: The type of $value inserted into the callback 733depends on the table's current value_class. 734 735 736 737 738=head1 SEE ALSO 739 740L<APR::Request::Error>, L<APR::Request::Param>, 741L<APR::Request::Cookie>, L<APR::Request::Parser> 742 743 744 745 746=head1 COPYRIGHT 747 748 Licensed to the Apache Software Foundation (ASF) under one or more 749 contributor license agreements. See the NOTICE file distributed with 750 this work for additional information regarding copyright ownership. 751 The ASF licenses this file to You under the Apache License, Version 2.0 752 (the "License"); you may not use this file except in compliance with 753 the License. You may obtain a copy of the License at 754 755 http://www.apache.org/licenses/LICENSE-2.0 756 757 Unless required by applicable law or agreed to in writing, software 758 distributed under the License is distributed on an "AS IS" BASIS, 759 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 760 See the License for the specific language governing permissions and 761 limitations under the License. 762