Debian Codegraph @

man/dynCurlReader.Rd

raw
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}