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