Create and configure a curl handle

Handles are the work horses of libcurl. A handle is used to configure a request with custom options, headers and payload. Once the handle has been set up, it can be passed to any of the download functions such as curl() ,curl_download() or curl_fetch_memory(). The handle will maintain state in between requests, including keep-alive connections, cookies and settings.

new_handle(...)

handle_setopt(handle, ..., .list = list())

handle_setheaders(handle, ..., .list = list())

handle_getheaders(handle)

handle_setform(handle, ..., .list = list())

handle_reset(handle)

Arguments

...

named options / headers to be set in the handle. To send a file, see form_file(). To list all allowed options, see curl_options()

handle

Handle to modify

.list

A named list of options. This is useful if you've created a list of options elsewhere, avoiding the use of do.call().

Value

A handle object (external pointer to the underlying curl handle). All functions modify the handle in place but also return the handle so you can create a pipeline of operations.

Details

Use new_handle() to create a new clean curl handle that can be configured with custom options and headers. Note that handle_setopt appends or overrides options in the handle, whereas handle_setheaders replaces the entire set of headers with the new ones. The handle_reset function resets only options/headers/forms in the handle. It does not affect active connections, cookies or response data from previous requests. The safest way to perform multiple independent requests is by using a separate handle for each request. There is very little performance overhead in creating handles.

The handle_setform function is used to perform a multipart/form-data HTTP POST request (a.k.a. posting a form). The form fields can be specified as strings, raw vectors (for binary data), or form_file and form_data for upload elements. See the examples.

See also

Other handles: handle_cookies()

Examples

h <- new_handle()
handle_setopt(h, customrequest = "PUT")
handle_setform(h, a = "1", b = "2")
r <- curl_fetch_memory("https://hb.cran.dev/put", h)
cat(rawToChar(r$content))
#> {
#>   "args": {}, 
#>   "data": "", 
#>   "files": {}, 
#>   "form": {
#>     "a": "1", 
#>     "b": "2"
#>   }, 
#>   "headers": {
#>     "Accept": "*/*", 
#>     "Accept-Encoding": "gzip, br", 
#>     "Cdn-Loop": "cloudflare; loops=1", 
#>     "Cf-Connecting-Ip": "3.145.237.107", 
#>     "Cf-Ipcountry": "US", 
#>     "Cf-Ray": "95c2505fa9407118-EWR", 
#>     "Cf-Visitor": "{\"scheme\":\"https\"}", 
#>     "Connection": "close", 
#>     "Content-Length": "228", 
#>     "Content-Type": "multipart/form-data; boundary=------------------------5d4d9d156414a510", 
#>     "Host": "httpbin:8080", 
#>     "User-Agent": "R/4.4.1 (ubuntu-22.04) R (4.4.1 x86_64-pc-linux-gnu x86_64 linux-gnu)"
#>   }, 
#>   "json": null, 
#>   "origin": "3.145.237.107", 
#>   "url": "https://httpbin:8080/put"
#> }

# Or use the list form
h <- new_handle()
handle_setopt(h, .list = list(customrequest = "PUT"))
handle_setform(h, .list = list(a = "1", b = "2"))
r <- curl_fetch_memory("https://hb.cran.dev/put", h)
cat(rawToChar(r$content))
#> {
#>   "args": {}, 
#>   "data": "", 
#>   "files": {}, 
#>   "form": {
#>     "a": "1", 
#>     "b": "2"
#>   }, 
#>   "headers": {
#>     "Accept": "*/*", 
#>     "Accept-Encoding": "gzip, br", 
#>     "Cdn-Loop": "cloudflare; loops=1", 
#>     "Cf-Connecting-Ip": "3.145.237.107", 
#>     "Cf-Ipcountry": "US", 
#>     "Cf-Ray": "95c2505ff9867118-EWR", 
#>     "Cf-Visitor": "{\"scheme\":\"https\"}", 
#>     "Connection": "close", 
#>     "Content-Length": "228", 
#>     "Content-Type": "multipart/form-data; boundary=------------------------879437d29100bec5", 
#>     "Host": "httpbin:8080", 
#>     "User-Agent": "R/4.4.1 (ubuntu-22.04) R (4.4.1 x86_64-pc-linux-gnu x86_64 linux-gnu)"
#>   }, 
#>   "json": null, 
#>   "origin": "3.145.237.107", 
#>   "url": "https://httpbin:8080/put"
#> }

# Posting multipart forms
h <- new_handle()
handle_setform(h,
  foo = "blabla",
  bar = charToRaw("boeboe"),
  iris = form_data(serialize(iris, NULL), "application/rda"),
  description = form_file(system.file("DESCRIPTION")),
  logo = form_file(file.path(R.home('doc'), "html/logo.jpg"), "image/jpeg")
)
req <- curl_fetch_memory("https://hb.cran.dev/post", handle = h)