Debian Codegraph @

man/curlPerform.Rd

raw
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