| 1 |
\name{getCurlHandle} |
| 2 |
\alias{getCurlHandle} |
| 3 |
\alias{getCurlMultiHandle} |
| 4 |
\alias{dupCurlHandle} |
| 5 |
\title{Create libcurl handles} |
| 6 |
\description{ |
| 7 |
These functions create and duplicate curl handles |
| 8 |
for use in calls to the HTTP facilities provided by |
| 9 |
that low-level language and this R-level interface. |
| 10 |
A curl handle is an opaque data type that contains a |
| 11 |
reference to the internal C-level data structure |
| 12 |
of libcurl for performing HTTP requests. |
| 13 |
|
| 14 |
The \code{getCurlMutliHandle} returns an object |
| 15 |
that can be used for concurrent, multiple requests. |
| 16 |
It is quite different from the regular curl handle |
| 17 |
and again, should be treated as an opaque data type. |
| 18 |
} |
| 19 |
\usage{ |
| 20 |
getCurlHandle(..., .opts = NULL, .encoding = integer(), |
| 21 |
.defaults = getOption("RCurlOptions")) |
| 22 |
dupCurlHandle(curl, ..., .opts = NULL, .encoding = integer()) |
| 23 |
getCurlMultiHandle(..., .handles = list(...)) |
| 24 |
} |
| 25 |
\arguments{ |
| 26 |
\item{curl}{the existing curl handle that is to be duplicated} |
| 27 |
\item{...}{a named list of curl options to set after the handle has |
| 28 |
been created. For \code{getCurlMultiHandle}, these values are |
| 29 |
invidivual curl handle objects, created via \code{getCurlHandle} or \code{dupCurlHandle}. } |
| 30 |
\item{.opts}{a named list or \code{CURLOptions} object identifying the |
| 31 |
curl options for the handle. These and the \code{...} arguments are |
| 32 |
used after the handle has been created.} |
| 33 |
\item{.encoding}{an integer or a string that explicitly identifies the |
| 34 |
encoding of the content that is returned by the HTTP server in its |
| 35 |
response to our query. The possible strings are |
| 36 |
\sQuote{UTF-8} or \sQuote{ISO-8859-1} |
| 37 |
and the integers should be specified symbolically |
| 38 |
as \code{CE_UTF8} and \code{CE_LATIN1}. |
| 39 |
Note that, by default, the package attempts to process the header of |
| 40 |
the HTTP response to determine the encoding. This argument is used |
| 41 |
when such information is erroneous and the caller knows the correct |
| 42 |
encoding. |
| 43 |
} |
| 44 |
\item{.defaults}{a collection of default values taken from R's |
| 45 |
global/session options. This is a parameter so that one can override |
| 46 |
it if necessary.} |
| 47 |
\item{.handles}{a list of curl handle objects that are used as the |
| 48 |
individual request handles within the multi-asynchronous requests} |
| 49 |
} |
| 50 |
\details{ |
| 51 |
These functions create C-level data structures. |
| 52 |
} |
| 53 |
\value{ |
| 54 |
An object of class \code{CURLHandle} |
| 55 |
which is simply a pointer to the memory for the C |
| 56 |
structure. |
| 57 |
} |
| 58 |
\references{Curl homepage \url{https://curl.se/}} |
| 59 |
\author{Duncan Temple Lang} |
| 60 |
|
| 61 |
|
| 62 |
\seealso{ |
| 63 |
\code{\link{getURL}} |
| 64 |
\code{\link{curlPerform}} |
| 65 |
} |
| 66 |
\examples{ |
| 67 |
|
| 68 |
options(RCurlOptions = list(verbose = TRUE, |
| 69 |
followlocation = TRUE, |
| 70 |
autoreferer = TRUE, |
| 71 |
nosignal = TRUE)) |
| 72 |
if(url.exists("https://r-project.org")) { |
| 73 |
x = getURL("https://r-project.org") |
| 74 |
# here we override one of these. |
| 75 |
x = getURL("https://r-project.org", verbose = FALSE) |
| 76 |
} |
| 77 |
} |
| 78 |
\keyword{IO} |
| 79 |
|
| 80 |
|