.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MongoDB::GridFSBucket::DownloadStream 3pm"
.TH MongoDB::GridFSBucket::DownloadStream 3pm "2022-06-30" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::GridFSBucket::DownloadStream \- File handle abstraction for downloading
.SH "VERSION"
.IX Header "VERSION"
version v2.2.2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    # OO API
\&    $stream = $bucket\->open_download_stream($file_id)
\&    while ( my $line = $stream\->readline ) {
\&        ...
\&    }
\&
\&    # Tied\-handle API
\&    $fh = $stream\->fh;
\&    while ( my $line = <$fh> ) {
\&        ...
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class provides a file abstraction for downloading.  You can stream
data from an object of this class using method calls or a tied-handle
interface.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "file_doc"
.IX Subsection "file_doc"
The file document for the file to be downloaded.
.PP
Valid file documents typically include the following fields:
.IP "\(bu" 4
_id – a unique \s-1ID\s0 for this document, typically a \s-1BSON::OID\s0 object. Legacy GridFS files may store this value as a different type.
.IP "\(bu" 4
length – the length of this stored file, in bytes
.IP "\(bu" 4
chunkSize – the size, in bytes, of each full data chunk of this file.
.IP "\(bu" 4
uploadDate – the date and time this file was added to GridFS, stored as a \s-1BSON\s0 datetime value and inflated per the bucket's bson_codec attribute.
.IP "\(bu" 4
filename – the name of this stored file; this does not need to be unique
.IP "\(bu" 4
metadata – any additional application-specific data
.IP "\(bu" 4
md5 – \s-1DEPRECATED\s0
.IP "\(bu" 4
contentType – \s-1DEPRECATED\s0
.IP "\(bu" 4
aliases – \s-1DEPRECATED\s0
.SH "METHODS"
.IX Header "METHODS"
.SS "fh"
.IX Subsection "fh"
.Vb 4
\&    my $fh = $downloadstream\->fh;
\&    while ( <$fh> ) {
\&        say($_);
\&    }
.Ve
.PP
Returns a new Perl file handle tied to this instance of DownloadStream that
can be operated on with the built-in functions \f(CW\*(C`read\*(C'\fR, \f(CW\*(C`readline\*(C'\fR,
\&\f(CW\*(C`getc\*(C'\fR, \f(CW\*(C`eof\*(C'\fR, \f(CW\*(C`fileno\*(C'\fR and \f(CW\*(C`close\*(C'\fR.
.PP
\&\fBImportant notes\fR:
.PP
Allowing one of these tied filehandles to fall out of scope will \s-1NOT\s0 cause
close to be called. This is due to the way tied file handles are
implemented in Perl.  For close to be called implicitly, all tied
filehandles and the original object must go out of scope.
.PP
Each file handle retrieved this way is tied back to the same object, so
calling close on multiple tied file handles and/or the original object will
have the same effect as calling close on the original object multiple
times.
.SS "close"
.IX Subsection "close"
.Vb 1
\&    $stream\->close
.Ve
.PP
Works like the builtin \f(CW\*(C`close\*(C'\fR.
.PP
\&\fBImportant notes:\fR
.IP "\(bu" 4
Calling close will also cause any tied file handles created for the stream to also close.
.IP "\(bu" 4
\&\f(CW\*(C`close\*(C'\fR will be automatically called when a stream object is destroyed.
.IP "\(bu" 4
Calling \f(CW\*(C`close\*(C'\fR repeatedly will warn.
.SS "eof"
.IX Subsection "eof"
.Vb 1
\&    if ( $stream\->eof() ) { ... }
.Ve
.PP
Works like the builtin \f(CW\*(C`eof\*(C'\fR.
.SS "fileno"
.IX Subsection "fileno"
.Vb 1
\&    if ( $stream\->fileno() ) { ... }
.Ve
.PP
Works like the builtin \f(CW\*(C`fileno\*(C'\fR, but it returns \-1 if the stream is open
and undef if closed.
.SS "getc"
.IX Subsection "getc"
.Vb 1
\&    $char = $stream\->getc();
.Ve
.PP
Works like the builtin \f(CW\*(C`getc\*(C'\fR.
.SS "read"
.IX Subsection "read"
.Vb 1
\&    $data = $stream\->read($buf, $length, $offset)
.Ve
.PP
Works like the builtin \f(CW\*(C`read\*(C'\fR.
.SS "readline"
.IX Subsection "readline"
.Vb 2
\&    $line  = $stream\->readline();
\&    @lines = $stream\->readline();
.Ve
.PP
Works like the builtin \f(CW\*(C`readline\*(C'\fR.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Rassi <rassi@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2020 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve