Debian Codegraph @

man/curlSetOpt.Rd

raw
1 \name{curlSetOpt}
2 \alias{curlSetOpt}
3 \title{Set values for the CURL options}
4 \description{
5 This function allows us to set values for the
6 possible options in the CURL data structure
7 that defines the HTTP request.
8 These options persist across calls in the
9 \code{CURLHandle} object.
10 }
11 \usage{
12 curlSetOpt(..., .opts = list(), curl = getCurlHandle(),
13 .encoding = integer(), .forceHeaderNames = FALSE,
14 .isProtected = FALSE)
15 }
16 %- maybe also 'usage' for other objects documented here.
17 \arguments{
18 \item{...}{a named list of curl options to set after the handle has
19 been created.}
20 \item{.opts}{a named list or \code{CURLOptions} object identifying the
21 curl options for the handle.}
22 \item{curl}{the \code{CURLHandle} object created earlier via
23 a call to \code{\link{getCurlHandle}} or
24 \code{\link{dupCurlHandle}}}
25 \item{.encoding}{an integer or a string that explicitly identifies the
26 encoding of the content that is returned by the HTTP server in its
27 response to our query. The possible strings are
28 \sQuote{UTF-8} or \sQuote{ISO-8859-1}
29 and the integers should be specified symbolically
30 as \code{CE_UTF8} and \code{CE_LATIN1}.
31 Note that, by default, the package attempts to process the header of
32 the HTTP response to determine the encoding. This argument is used
33 when such information is erroneous and the caller knows the correct
34 encoding.
35 }
36 \item{.forceHeaderNames}{a logical value which if \code{TRUE}
37 allows the caller to explicitly indicate that the HTTPHEADER
38 option needs to have the names prefixed to the strings.
39 This removes any ambiguity caused by the presence of ':' in the
40 values appearing to be the separator between the name and the value
41 of the \code{name: value} pairs of the HTTP header.}
42 \item{.isProtected}{
43 a logical vector (or value that is repeated) specifying which
44 of the values in \dots and \code{.opts} need to be explicitly
45 protected from garbage collection or not.
46 The basic idea is that we specify \code{FALSE} if
47 the value being set for the curl option may be garbage collected
48 before the \code{curl} handle is garbage collected. This would leave
49 the \code{curl} object in an inconsistent state, referring to an R
50 object (i.e. an R function), which may be used after the R object has been garbage collected.
51 }
52 }
53 \value{
54 An integer value giving the status of the return.
55 This should be 0 as if there was an error in the libcurl
56 mechiansim, we will throw it there.
57 }
58
59 \references{Curl homepage \url{https://curl.se/}}
60 \author{Duncan Temple Lang}
61
62 \seealso{
63 \code{\link{getCurlHandle}}
64 \code{\link{dupCurlHandle}}
65 }
66 \examples{
67 tryCatch({
68
69 curl = getCurlHandle()
70 # Note the header that extends across two lines with the second line
71 # prefixed with white space.
72 curlSetOpt( .opts = list(httpheader = c(Date = "Wed, 1/2/2000 10:01:01",
73 foo="abc\n extra line"), verbose = TRUE),
74 curl = curl)
75 ans = getURL("https://r-project.org", curl = curl)
76 }, GenericCurlError = identity)
77 }
78 \keyword{IO}
79
80