Debian Codegraph @

README

raw
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