| 1 |
\name{curlPerform} |
| 2 |
\alias{curlPerform} |
| 3 |
\alias{curlMultiPerform} |
| 4 |
\title{Perform the HTTP query} |
| 5 |
\description{ |
| 6 |
These function causes the HTTP query, that has been specified |
| 7 |
via the different options in this and other calls, to be sent and processed. |
| 8 |
Unlike in curl itself, |
| 9 |
for \code{curlPerform} one can specify all the options |
| 10 |
in this call as an atomic invocation. |
| 11 |
This avoids having to set the options and then perform |
| 12 |
the action. Instead, this is all done in one call. |
| 13 |
|
| 14 |
For \code{curlMultiPerform}, one must add the relevant |
| 15 |
\code{\link{CURLHandle-class}} objects to the |
| 16 |
\code{\link{MultiCURLHandle-class}} objects |
| 17 |
before issuing the call to \code{curlMultiPerform}. |
| 18 |
} |
| 19 |
\usage{ |
| 20 |
curlPerform(..., .opts = list(), curl = getCurlHandle(), .encoding = integer()) |
| 21 |
curlMultiPerform(curl, multiple = TRUE) |
| 22 |
} |
| 23 |
\arguments{ |
| 24 |
\item{curl}{for \code{curlPerform}, this is the \code{CURLHandle} |
| 25 |
object giving the structure for the |
| 26 |
options and that will process the command. |
| 27 |
For \code{curlMultiPerform}, this is an object of class |
| 28 |
code \code{\link{MultiCURLHandle-class}}.} |
| 29 |
\item{...}{a named list of curl options to set after the handle has |
| 30 |
been created.} |
| 31 |
\item{.opts}{a named list or \code{CURLOptions} object identifying the |
| 32 |
curl options for the handle. This is merged with the values of \dots |
| 33 |
to create the actual options for the curl handle in the request.} |
| 34 |
\item{multiple}{a logical value. If \code{TRUE} and the internal call |
| 35 |
to \code{curl_multi_perform} returns a value that indicates there is |
| 36 |
still data available from one of the HTTP responses, we call |
| 37 |
\code{curl_multi_perform} repeatedly until there is no more data |
| 38 |
available at that time. If this is \code{FALSE}, we call |
| 39 |
\code{curl_multi_perform} once and return, regardless of whether |
| 40 |
there is more data available. This is convenient if we want to limit |
| 41 |
the time spent in the call to \code{curlMultiPerform}. |
| 42 |
} |
| 43 |
\item{.encoding}{an integer or a string that explicitly identifies the |
| 44 |
encoding of the content that is returned by the HTTP server in its |
| 45 |
response to our query. The possible strings are |
| 46 |
\sQuote{UTF-8} or \sQuote{ISO-8859-1} |
| 47 |
and the integers should be specified symbolically |
| 48 |
as \code{CE_UTF8} and \code{CE_LATIN1}. |
| 49 |
Note that, by default, the package attempts to process the header of |
| 50 |
the HTTP response to determine the encoding. This argument is used |
| 51 |
when such information is erroneous and the caller knows the correct |
| 52 |
encoding. |
| 53 |
|
| 54 |
Note that the encoding argument is not a regular libcurl option and |
| 55 |
is handled specially by RCurl. But as a result, it is not unset |
| 56 |
in subsequent uses of the curl handle (\code{curl}). |
| 57 |
} |
| 58 |
} |
| 59 |
\value{ |
| 60 |
A integer value indicating the status of the request. |
| 61 |
This should be 0 as other errors will generate |
| 62 |
errors. |
| 63 |
} |
| 64 |
\references{Curl homepage \url{https://curl.se/}} |
| 65 |
\author{Duncan Temple Lang} |
| 66 |
|
| 67 |
\seealso{ |
| 68 |
\code{\link{getURL}} |
| 69 |
\code{\link{postForm}} |
| 70 |
\code{\link{getForm}} |
| 71 |
\code{\link{curlSetOpt}} |
| 72 |
} |
| 73 |
\examples{ |
| 74 |
tryCatch(withAutoprint({ |
| 75 |
h = basicTextGatherer() |
| 76 |
curlPerform(url = "https://r-project.org", writefunction = h$update) |
| 77 |
# Now read the text that was cumulated during the query response. |
| 78 |
cat(h$value()) |
| 79 |
}), GenericCurlError = identity) |
| 80 |
|
| 81 |
|
| 82 |
\dontrun{ |
| 83 |
## this no longer exists |
| 84 |
if(url.exists("http://services.soaplite.com/hibye.cgi")) withAutoprint({ |
| 85 |
# SOAP request |
| 86 |
body = '<?xml version="1.0" encoding="UTF-8"?>\ |
| 87 |
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" \ |
| 88 |
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" \ |
| 89 |
xmlns:xsd="http://www.w3.org/1999/XMLSchema" \ |
| 90 |
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" \ |
| 91 |
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance">\ |
| 92 |
<SOAP-ENV:Body>\ |
| 93 |
<namesp1:hi xmlns:namesp1="http://www.soaplite.com/Demo"/>\ |
| 94 |
</SOAP-ENV:Body>\ |
| 95 |
</SOAP-ENV:Envelope>\n' |
| 96 |
|
| 97 |
|
| 98 |
h$reset() |
| 99 |
curlPerform(url = "http://services.soaplite.com/hibye.cgi", |
| 100 |
httpheader=c(Accept="text/xml", Accept="multipart/*", |
| 101 |
SOAPAction='"http://www.soaplite.com/Demo#hi"', |
| 102 |
'Content-Type' = "text/xml; charset=utf-8"), |
| 103 |
postfields=body, |
| 104 |
writefunction = h$update, |
| 105 |
verbose = TRUE |
| 106 |
) |
| 107 |
|
| 108 |
body = h$value() |
| 109 |
|
| 110 |
}) |
| 111 |
} |
| 112 |
|
| 113 |
|
| 114 |
# Using a C routine as the reader of the body of the response. |
| 115 |
tryCatch(withAutoprint({ |
| 116 |
routine = getNativeSymbolInfo("R_internalWriteTest", PACKAGE = "RCurl")$address |
| 117 |
curlPerform(URL = "https://r-project.org", |
| 118 |
writefunction = routine) |
| 119 |
}), GenericCurlError = identity) |
| 120 |
} |
| 121 |
\keyword{IO} |
| 122 |
|
| 123 |
|