handle {curl} | R Documentation

## Create and configure a curl handle

### Description

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.

### Usage

    new_handle(...)

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

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

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

    handle_reset(handle)

    handle_data(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()`.

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

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

### 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("http://httpbin.org/put", h)
    cat(rawToChar(r$content))

    # 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("http://httpbin.org/put", h)
    cat(rawToChar(r$content))

[Package curl version 3.3 Index]