| 1 |
NAME |
| 2 |
CGI::Application::Plugin::Stream - CGI::Application Plugin for streaming |
| 3 |
files |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
use CGI::Application::Plugin::Stream (qw/stream_file/); |
| 7 |
|
| 8 |
sub runmode { |
| 9 |
# ... |
| 10 |
|
| 11 |
# Set up any headers you want to set explicitly |
| 12 |
# using header_props() or header_add() as usual |
| 13 |
|
| 14 |
#... |
| 15 |
|
| 16 |
if ( $self->stream_file( $file ) ) { |
| 17 |
return; |
| 18 |
} else { |
| 19 |
return $self->error_mode(); |
| 20 |
} |
| 21 |
} |
| 22 |
|
| 23 |
DESCRIPTION |
| 24 |
This plugin provides a way to stream a file back to the user. |
| 25 |
|
| 26 |
This is useful if you are creating a PDF or Spreadsheet document |
| 27 |
dynamically to deliver to the user. |
| 28 |
|
| 29 |
The file is read and printed in small chunks to keep memory consumption |
| 30 |
down. |
| 31 |
|
| 32 |
This plugin is a consumer, as in your runmode shouldn't try to do any |
| 33 |
output or anything afterwards. This plugin affects the HTTP response |
| 34 |
headers, so anything you do afterwards will probably not work. If you |
| 35 |
pass along a filehandle, we'll make sure to close it for you. |
| 36 |
|
| 37 |
It's recommended that you increment $| (or set it to 1), which will |
| 38 |
autoflush the buffer as your application is streaming out the file. |
| 39 |
|
| 40 |
METHODS |
| 41 |
stream_file() |
| 42 |
$self->stream_file($fh); |
| 43 |
$self->stream_file( '/path/to/file',2048); |
| 44 |
|
| 45 |
This method can take two parameters, the first the path to the file or a |
| 46 |
filehandle and the second, an optional number of bytes to determine the |
| 47 |
chunk size of the stream. It defaults to 1024. |
| 48 |
|
| 49 |
It will either stream a file to the user or return false if it fails, |
| 50 |
perhaps because it couldn't find the file you referenced. |
| 51 |
|
| 52 |
We highly recommend you provide a file name if passing along a |
| 53 |
filehandle, as we won't be able to deduce the file name, and will use |
| 54 |
'FILE' by default. Example: |
| 55 |
|
| 56 |
$self->header_add( -attachment => 'my_file.txt' ); |
| 57 |
|
| 58 |
With both a file handle or file name, we will try to determine the |
| 59 |
correct content type by using File::MMagic. A default of |
| 60 |
'application/octet-stream' will be used if File::MMagic can't figure it |
| 61 |
out. |
| 62 |
|
| 63 |
The size will be calculated and added to the headers as well. |
| 64 |
|
| 65 |
Again, you can set these explicitly if you want as well: |
| 66 |
|
| 67 |
$self->header_add( |
| 68 |
-type => 'text/plain', |
| 69 |
-Content_Length => 42, # bytes |
| 70 |
); |
| 71 |
|
| 72 |
AUTHOR |
| 73 |
Jason Purdy, <[email protected]>, with inspiration from Tobias Henoeckl |
| 74 |
and tremendous support from the cgiapp mailing list. |
| 75 |
|
| 76 |
Mark Stosberg also contributed to this module. |
| 77 |
|
| 78 |
SEE ALSO |
| 79 |
CGI::Application, <http://www.cgi-app.org>, "CREATING A STANDARD HTTP |
| 80 |
HEADER" in CGI.pm, |
| 81 |
<http://www.mail-archive.com/[email protected]/msg02660.html>, |
| 82 |
File::Basename, "$|" in perlvar |
| 83 |
|
| 84 |
LICENSE |
| 85 |
Copyright (C) 2004-2005 Jason Purdy, <[email protected]> |
| 86 |
|
| 87 |
This library is free software. You can modify and or distribute it under |
| 88 |
the same terms as Perl itself. |
| 89 |
|