| 1 |
\name{dynCurlReader} |
| 2 |
\alias{dynCurlReader} |
| 3 |
%- Also NEED an '\alias' for EACH other topic documented here. |
| 4 |
\title{Dynamically determine content-type of body from HTTP header and |
| 5 |
set body reader} |
| 6 |
\description{ |
| 7 |
This function is used for the \code{writefunction} |
| 8 |
option in a curl HTTP request. |
| 9 |
The idea is that we read the header of the HTTP response |
| 10 |
and when our code determines that the header is complete |
| 11 |
(the presence of a blank line), it examines the contents |
| 12 |
of the header and finds a Content-Type field. |
| 13 |
It uses the value of this to determine the nature of the |
| 14 |
body of the HTTP response and dynamically (re)sets the reader |
| 15 |
for the curl handle appropriately. If the content is binary, |
| 16 |
it collects the content into a \code{raw} vector; |
| 17 |
if it is text, it sets the appropriate character encoding |
| 18 |
and collects the content into a character vector. |
| 19 |
|
| 20 |
This function is like \code{\link{basicTextGatherer}} |
| 21 |
but behaves dynamically by determining how to read the content |
| 22 |
based on the header of the HTTP response. |
| 23 |
This function returns a list of functions that are used |
| 24 |
to update and query a shared state across calls. |
| 25 |
|
| 26 |
} |
| 27 |
\usage{ |
| 28 |
dynCurlReader(curl = getCurlHandle(), txt = character(), max = NA, |
| 29 |
value = NULL, verbose = FALSE, binary = NA, baseURL = NA, |
| 30 |
isHTTP = NA, encoding = NA) |
| 31 |
} |
| 32 |
%- maybe also 'usage' for other objects documented here. |
| 33 |
\arguments{ |
| 34 |
\item{curl}{the curl handle to be used for the request. It is |
| 35 |
essential that this handle be used in the low-level call to |
| 36 |
\code{\link{curlPerform}} so that the update |
| 37 |
element sets the reader for the body on the appropriate |
| 38 |
curl handle that is used in the request. |
| 39 |
} |
| 40 |
\item{txt}{initial value of the text. This is almost always an empty |
| 41 |
character vector.} |
| 42 |
\item{max}{the maximum number of characters to read. This is almost |
| 43 |
always \code{NA}.} |
| 44 |
\item{value}{a function that can be specified which will be used to |
| 45 |
convert the body of the response from text or raw in a customized |
| 46 |
manner, |
| 47 |
e.g. uncompress a gzip body. This can als be done explicitly |
| 48 |
with a call \code{fun(reader$value())} after the body has been read. |
| 49 |
The advantage of specifying the function in the constructor of the |
| 50 |
reader is that the end-user doesn't have to know which function to |
| 51 |
use to do the conversion. |
| 52 |
} |
| 53 |
\item{verbose}{a logical value indicating whether messages about |
| 54 |
progress and operations are written on the console as the |
| 55 |
header and body are processed. |
| 56 |
} |
| 57 |
\item{binary}{a logical value indicating whether the caller knows |
| 58 |
whether the resulting content is binary (\code{TRUE}) or not |
| 59 |
(\code{FALSE}) or unknown (\code{NA}). |
| 60 |
} |
| 61 |
\item{baseURL}{the URL of the request which can be used to follow |
| 62 |
links to other URLs that are described relative to this. |
| 63 |
} |
| 64 |
\item{isHTTP}{a logical value indicating whether the request/download uses |
| 65 |
HTTP or not. If this is \code{NA}, we determine this when the header |
| 66 |
is received. If the caller knows this is an FTP or other request, |
| 67 |
they can specify this when creating the reader.} |
| 68 |
\item{encoding}{a string that allows the caller to specify and override |
| 69 |
the encoding of the result. This is used to convert text returned |
| 70 |
from the server.} |
| 71 |
} |
| 72 |
\value{ |
| 73 |
A list with 5 elements all of which are functions. These are |
| 74 |
\item{update}{the function that does the actual reading/processing of |
| 75 |
the content that libcurl passes to it from the header and the |
| 76 |
body. This is the work-horse of the reader.} |
| 77 |
\item{value}{a function to get the body of the response} |
| 78 |
\item{header}{a function to get the content of the HTPP header} |
| 79 |
\item{reset}{a function to reset the internal contents which allows |
| 80 |
the same reader to be re-used in subsequent HTTP requests} |
| 81 |
\item{curl}{accessor function for the curl handle specified in the |
| 82 |
call to create this dynamic reader object.} |
| 83 |
|
| 84 |
This list has the S3 class vector |
| 85 |
\code{c("DynamicRCurlTextHandler", "RCurlTextHandler", "RCurlCallbackFunction")} |
| 86 |
} |
| 87 |
\references{libcurl \url{https://curl.se/}} |
| 88 |
\author{Duncan Temple Lang} |
| 89 |
|
| 90 |
\seealso{ |
| 91 |
\code{\link{basicTextGatherer}} |
| 92 |
\code{\link{curlPerform}} |
| 93 |
\code{\link{getURLContent}} |
| 94 |
} |
| 95 |
\examples{ |
| 96 |
|
| 97 |
# Each of these examples can be done with getURLContent(). |
| 98 |
# These are here just to illustrate the dynamic reader. |
| 99 |
tryCatch(withAutoprint({ |
| 100 |
header = dynCurlReader() |
| 101 |
curlPerform(url = "https://www.r-project.org/Rlogo.png", |
| 102 |
headerfunction = header$update, curl = header$curl()) |
| 103 |
class( header$value() ) |
| 104 |
length( header$value() ) |
| 105 |
}), GenericCurlError = identity) |
| 106 |
|
| 107 |
tryCatch(withAutoprint({ |
| 108 |
# gzip example. |
| 109 |
header = dynCurlReader() |
| 110 |
curlPerform(url = "https://aitap.grebedoc.dev/RCurl/dd.gz", |
| 111 |
headerfunction = header$update, curl = header$curl()) |
| 112 |
class( header$value() ) |
| 113 |
length( header$value() ) |
| 114 |
|
| 115 |
if (getRversion() >= "4") |
| 116 |
cat(memDecompress(header$value(), asChar = TRUE)) |
| 117 |
## or cat(Rcompression::gunzip(header$value())) |
| 118 |
}), GenericCurlError = identity) |
| 119 |
|
| 120 |
|
| 121 |
# Character encoding example |
| 122 |
\dontrun{ |
| 123 |
header = dynCurlReader() |
| 124 |
curlPerform(url = "http://www.razorvine.net/test/utf8form/formaccepter.sn", |
| 125 |
postfields = c(text = "ABC", outputencoding = "UTF-8"), |
| 126 |
verbose = TRUE, |
| 127 |
writefunction = header$update, curl = header$curl()) |
| 128 |
class( header$value() ) |
| 129 |
Encoding( header$value() ) |
| 130 |
} |
| 131 |
} |
| 132 |
\keyword{IO} |
| 133 |
\concept{binary} |