stas 2004/07/02 16:17:53 Modified: src/docs/2.0/api/Apache RequestIO.pod src/docs/2.0/user/porting compat.pod Log: complete Apache::RequestIO Revision Changes Path 1.5 +294 -141 modperl-docs/src/docs/2.0/api/Apache/RequestIO.pod Index: RequestIO.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/RequestIO.pod,v retrieving revision 1.4 retrieving revision 1.5 diff -u -u -r1.4 -r1.5 --- RequestIO.pod 22 May 2004 02:03:27 -0000 1.4 +++ RequestIO.pod 2 Jul 2004 23:17:53 -0000 1.5 @@ -8,8 +8,20 @@ =head1 Synopsis use Apache::RequestIO (); - -META: to be completed + + $rc = $r->discard_request_body(); + + $r->print("foo", "bar"); + $r->puts("foo", "bar"); # same as print, but no flushing + $r->printf("%s $d", "foo", 5); + + $r->read($buffer, $len); + + $r->rflush(); + + $r->sendfile($filename); + + $r->write("foobartarcar", 3, 5); @@ -31,112 +43,142 @@ =head2 C<discard_request_body> -META: Autogenerated - needs to be reviewed/completed - In HTTP/1.1, any method can have a body. However, most GET handlers wouldn't know what to do with a request body if they received one. -This helper routine tests for and reads any message body in the request, -simply discarding whatever it receives. We need to do this because -failing to read the request body would cause it to be interpreted -as the next request on a persistent connection. +This helper routine tests for and reads any message body in the +request, simply discarding whatever it receives. We need to do this +because failing to read the request body would cause it to be +interpreted as the next request on a persistent connection. - $ret = $r->discard_request_body(); + $rc = $r->discard_request_body(); =over 4 -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +=item obj: C<$r> +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> ) The current request -=item ret: C<$ret> (integer) +=item ret: C<$rc> ( integer ) -error status if request is malformed, Apache::OK otherwise +C<L<APR::Const status constant|docs::2.0::api::APR::Const>> if request +is malformed, C<Apache::OK> otherwise. + +=item since: 1.99_10 =back +Since we return an error status if the request is malformed, this +routine should be called at the beginning of a no-body handler, e.g., + use Apache::Const -compile => qw(OK); + $rc = $r->discard_request_body; + return $rc if $rc != Apache::OK; -=head2 C<setup_client_block> -META: Autogenerated - needs to be reviewed/completed -META: I think this method is deprecated along with other client_block -methods, use plain $r-E<lt>read() instead. +=head2 C<print> -Setup the client to allow Apache to read the request body. +Send data to the client. - $ret = $r->setup_client_block($read_policy); + $cnt = $r->print(@msg); =over 4 -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +=item obj: C<$r> +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> ) -The current request +=item arg1: C<@msg> ( ARRAY ) -=item arg1: C<$read_policy> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +Data to send -How the server should interpret a chunked transfer-encoding. One of: +=item ret: C<$cnt> ( number ) - REQUEST_NO_BODY Send 413 error if message has any body - REQUEST_CHUNKED_ERROR Send 411 error if body without Content-Length - REQUEST_CHUNKED_DECHUNK If chunked, remove the chunks for me. +How many bytes were sent (or buffered) -=item ret: C<$ret> (integer) +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>> -either OK or an error code +=item since: 1.99_10 =back +The data is flushed only if STDOUT stream's C<$|> is true. Otherwise +it's buffered up to the size of the buffer, flushing only excessive +data. -=head2 C<should_client_block> +=head2 C<printf> -META: Autogenerated - needs to be reviewed/completed +Format and send data to the client (same as C<printf>). -META: I think this method is deprecated along with other client_block -methods, use plain $r-E<lt>read() instead. + $cnt = $r->printf($format, @args); -Determine if the client has sent any data. This also sends a -100 Continue response to HTTP/1.1 clients, so modules should not be called -until the module is ready to read content. +=over 4 - $ret = $r->should_client_block(); +=item obj: C<$r> +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> ) -=over 4 +=item arg1: C<$format> ( string ) -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +Format string, as in the Perl core C<printf> function. -The current request +=item arg2: C<@args> ( ARRAY ) + +Arguments to be formatted, as in the Perl core C<printf> function. -=item ret: C<$ret> (integer) +=item ret: C<$cnt> ( number ) -0 if there is no message to read, 1 otherwise +How many bytes were sent (or buffered) + +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>> + +=item since: 1.99_10 =back +The data is flushed only if STDOUT stream's C<$|> is true. Otherwise +it's buffered up to the size of the buffer, flushing only excessive +data. -=head2 C<print> -Send data to the client. +=head2 C<puts> + +Send data to the client - $ret = $r->print(@msg); + $cnt = $r->puts(@msg); =over 4 -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +=item obj: C<$r> +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> ) + +=item arg1: C<@msg> ( ARRAY ) + +Data to send -=item arg1: C<@msg> (ARRAY) +=item ret: C<$cnt> ( number ) -=item ret: C<$ret> (number) +How many bytes were sent (or buffered) + +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>> + +=item since: 1.99_10 =back +C<puts()> is similar to C<L<print()|/C_print_>>, but it won't attempt +to flush data, no matter what the value of STDOUT stream's C<$|> +is. Therefore assuming that STDOUT stream's C<$|> is true, this method +should be a tiny bit faster than C<L<print()|/C_print_>>, especially +if small strings are printed. + + @@ -144,26 +186,43 @@ Read data from the client. - $read_count = $r->read($buffer, $len, $offset); - -META: same as CORE::read, minus the filehandle argument + $cnt = $r->read($buffer, $len); + $cnt = $r->read($buffer, $len, $offset); =over 4 -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +=item obj: C<$r> +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> ) + +=item arg1: C<$buffer> ( SCALAR ) + +The buffer to populate with the read data + +=item arg2: C<$len> ( number ) -=item arg1: C<$buffer> (scalar) +How many bytes to attempt to read -=item arg2: C<$len> (scalar) +=item opt arg3: C<$offset> ( number ) -=item arg3: C<$offset> (number) +If a non-zero C<$offset> is specified, the read data will be placed at +that offset in the C<$buffer>. -=item ret: C<$read_count> (number) +META: negative offset and \0 padding are not supported at the moment + +=item ret: C<$cnt> ( number ) How many characters were actually read +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>> + +=item since: 1.99_10 + =back +This method shares a lot of similarities with the Perl core C<read()> +function. The main difference in the error handling, which is done via +C<L<APR::Error exceptions|docs::2.0::api::APR::Error>> + @@ -171,39 +230,74 @@ Flush any buffered data to the client. - $ret = $r->rflush(); + $r->rflush(); =over 4 -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +=item obj: C<$r> +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> ) + +=item ret: no return value -=item ret: C<$ret> (integer) +=item since: 1.99_15 =back -Unless C<$|> E<gt> 0, data sent via C<L<$r-E<gt>print()|/C_print_>> is -buffered. This method flushes that data to the client. +Unless STDOUT stream's C<$|> is false, data sent via +C<L<$r-E<gt>print()|/C_print_>> is buffered. This method flushes that +data to the client. + =head2 C<sendfile> -META: Autogenerated - needs to be reviewed/completed +Send a file or a part of it - $ret = $r->sendfile($filename, $offset, $len); + $rc = $r->sendfile($filename); + $rc = $r->sendfile($filename, $offset); + $rc = $r->sendfile($filename, $offset, $len); =over 4 -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +=item obj: C<$r> +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> ) + +=item arg1: C<$filename> ( string ) + +The full path to the file (using C</> on all systems) + +=item opt arg2: C<$offset> ( integer ) + +Offset into the file to start sending. + +No offset is used if C<$offset> is not specified. -=item arg1: C<$filename> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +=item opt arg3: C<$len> ( integer ) -=item arg2: C<$offset> (integer) +How many bytes to send. -=item arg3: C<$len> (integer) +If not specified the whole file is sent (or a part of it, if +C<$offset> if specified) -=item ret: C<$ret> (integer) +=item ret: C<$rc> ( C<L<APR::Const status +constant|docs::2.0::api::APR::Const>> ) + +On success, +C<L<APR::SUCCESS|docs::2.0::api::APR::Const/C_APR__SUCCESS_>> is +returned. + +In case of a failure -- a failure code is returned, in which case +normally it should be returned to the caller. + +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>> + +Exceptions are thrown only when this function is called in the VOID +context. So if you don't want to handle the errors, just don't ask for +a return value and the function will handle all the errors on its own. + +=item since: 1.99_15 =back @@ -213,218 +307,277 @@ =head2 C<write> -META: Autogenerated - needs to be reviewed/completed - -Write data to the client +Send partial string to the client - $ret = $r->write($buffer, $bufsiz, $offset); + $cnt = $r->write($buffer); + $cnt = $r->write($buffer, $len); + $cnt = $r->write($buffer, $len, $offset); =over 4 -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +=item obj: C<$r> +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> ) + +=item arg1: C<$buffer> ( SCALAR ) -=item arg1: C<$buffer> (scalar) +The string with data -=item arg2: C<$bufsiz> (scalar) +=item opt arg2: C<$len> ( SCALAR ) -=item arg3: C<$offset> (number) +How many bytes to send. If not specified, or -1 is specified, all the +data in C<$buffer> (or starting from C<$offset>) will be sent. -=item ret: C<$ret> (number) +=item opt arg3: C<$offset> ( number ) + +Offset into the C<$buffer> string. + +=item ret: C<$cnt> ( number ) + +How many bytes were sent (or buffered) + +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>> + +=item since: 1.99_10 =back +Examples: +Assuming that we have a string: + $string = "123456789"; -=head1 TIE Interface +Then: -=head2 C<OPEN> + $r->write($string); -META: Autogenerated - needs to be reviewed/completed +sends: - $ret = OPEN($self, $arg1, $arg2); + 123456789 -=over 4 +Whereas: -=item obj: C<$self> (scalar) + $r->write($string, 3); -=item arg1: C<$arg1> (scalar) +sends: -=item arg2: C<$arg2> (scalar) + 123 -=item ret: C<$ret> (integer) +And: -=back + $r->write($string, 3, 5); +sends: -=head2 C<UNTIE> + 678 -META: Autogenerated - needs to be reviewed/completed +Finally: + $r->write($string, -1, 5); +sends: - $ret = $r->UNTIE($refcnt); + 6789 -=over 4 -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) -=item arg1: C<$refcnt> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) -=item ret: C<$ret> (scalar) -=back +=head1 TIE Interface +The TIE interface implementation. This interface is used for HTTP +request handlers, when running under C<L<SetHandler +perl-script|docs::2.0::user::config::config/C_perl_script_>> and +Perl doesn't have perlio enabled. -=head2 C<PRINTF> +See the I<perltie> manpage for more information. -META: Autogenerated - needs to be reviewed/completed - $ret = PRINTF(...); +=head2 C<BINMODE> =over 4 -=item obj: C<...> (scalar) - -=item ret: C<$ret> (number) +=item since: 1.99_10 =back +NoOP +See the I<binmode> Perl entry in the I<perlfunc> manpage =head2 C<CLOSE> -META: Autogenerated - needs to be reviewed/completed +=over 4 - $ret = $r->CLOSE(); +=item since: 1.99_10 -=over 4 +=back -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +NoOP -=item ret: C<$ret> (scalar) +See the I<close> Perl entry in the I<perlfunc> manpage -=back +=head2 C<FILENO> +=over 4 +=item since: 1.99_10 -=head2 C<PRINT> +=back -META: Autogenerated - needs to be reviewed/completed +See the I<fileno> Perl entry in the I<perlfunc> manpage - $ret = PRINT(...); -=over 4 +=head2 C<GETC> -=item obj: C<...> (scalar) +=over 4 -=item ret: C<$ret> (number) +=item since: 1.99_10 =back +See the I<getc> Perl entry in the I<perlfunc> manpage -=head2 C<BINMODE> +=head2 C<OPEN> -META: Autogenerated - needs to be reviewed/completed +=over 4 +=item since: 1.99_10 +=back - $ret = $r->BINMODE(); +See the I<open> Perl entry in the I<perlfunc> manpage -=over 4 -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) -=item ret: C<$ret> (scalar) -=back +=head2 C<PRINT> + +=over 4 +=item since: 1.99_10 +=back +See the I<print> Perl entry in the I<perlfunc> manpage -=head2 C<WRITE> -META: Autogenerated - needs to be reviewed/completed - $ret = $r->WRITE($buffer, $bufsiz, $offset); +=head2 C<PRINTF> =over 4 -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) +=item since: 1.99_10 -=item arg1: C<$buffer> (scalar) +=back -=item arg2: C<$bufsiz> (scalar) +See the I<printf> Perl entry in the I<perlfunc> manpage -=item arg3: C<$offset> (integer) -=item ret: C<$ret> (integer) + + +=head2 C<READ> + +=over 4 + +=item since: 1.99_10 =back +See the I<read> Perl entry in the I<perlfunc> manpage + =head2 C<TIEHANDLE> -META: Autogenerated - needs to be reviewed/completed +=over 4 + +=item since: 1.99_10 + +=back +See the I<tie> Perl entry in the I<perlfunc> manpage - $ret = TIEHANDLE($stashsv, $sv); + + +=head2 C<UNTIE> =over 4 -=item obj: C<$stashsv> (scalar) +=item since: 1.99_10 -=item arg1: C<$sv> (scalar) +=back -=item ret: C<$ret> (scalar) +NoOP + +See the I<untie> Perl entry in the I<perlfunc> manpage + + + + + +=head2 C<WRITE> + +=over 4 + +=item since: 1.99_10 =back +See the I<write> Perl entry in the I<perlfunc> manpage -=head2 C<READ> +=head1 Deprecated API -META: Autogenerated - needs to be reviewed/completed +The following methods are deprecated, Apache plans to remove those in +the future, therefore avoid using them. - $ret = $r->READ($buffer, $len, $offset); +=head2 C<get_client_block> -=over 4 +This method is deprecated since the C implementation is buggy and we +don't want you to use it at all. Instead use the plain +C<L<$r-E<gt>read()|/C_read_>>. -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>) -=item arg1: C<$buffer> (scalar) -=item arg2: C<$len> (scalar) -=item arg3: C<$offset> (integer) +=head2 C<setup_client_block> + +This method is deprecated since +C<L<$r-E<gt>get_client_block|/C__get_client_block_>> is deprecated. + + + + +=head2 C<should_client_block> + +This method is deprecated since +C<L<$r-E<gt>get_client_block|/C__get_client_block_>> is deprecated. -=item ret: C<$ret> (scalar) -=back 1.51 +11 -14 modperl-docs/src/docs/2.0/user/porting/compat.pod Index: compat.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/porting/compat.pod,v retrieving revision 1.50 retrieving revision 1.51 diff -u -u -r1.50 -r1.51 --- compat.pod 22 May 2004 21:55:52 -0000 1.50 +++ compat.pod 2 Jul 2004 23:17:53 -0000 1.51 @@ -858,8 +858,7 @@ =item * if one wishes to simply read POST data, there is the more modern -C<{setup,should,get}_client_block> API, and even more modern filter -API, along with continued support for C<read(STDIN, ...)> and +filter API, along with continued support for C<read(STDIN, ...)> and C<$r-E<gt>read($buf, $r-E<gt>headers_in-E<gt>{'content-length'}>) =back @@ -1019,8 +1018,9 @@ =head2 C<$r-E<gt>send_fd> -Apache 2.0 provides a new method C<sendfile()> instead of C<send_fd>, -so if your code used to do: +mod_perl 2.0 provides a new method +C<L<sendfile()|docs::2.0::api::Apache::RequestIO/C_sendfile_>> instead +of C<send_fd>, so if your code used to do: open my $fh, "<$file" or die "$!"; $r->send_fd($fh); @@ -1028,19 +1028,16 @@ now all you need is: - $r->sendfile($fh); + $r->sendfile($file); -There is also a compatibility implementation in pure perl in -C<L<Apache::compat|docs::2.0::api::Apache::compat>>. +There is also a compatibility implementation of send_fd in pure perl +in C<L<Apache::compat|docs::2.0::api::Apache::compat>>. +XXX: later we may provide a direct access to the real send_fd. That +will be possible if we figure out how to portably convert PerlIO/FILE +into apr_file_t (with help of apr_os_file_put, which expects a native +filehandle, so I'm not sure whether this will work on win32). -=head2 C<$r-E<gt>send_fd_length> - -currently available only in the 1.0 compatibility layer. The problem -is that Apache has changed the API and its functionality. See the -implementation in C<L<Apache::compat|docs::2.0::api::Apache::compat>>. - -XXX: needs a better resolution =head2 C<$r-E<gt>send_http_header>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]