curl (version 2.3)

curl_fetch_memory: Fetch the contents of a URL

Description

Low-level bindings to write data from a URL into memory, disk or a callback function. These are mainly intended for httr, most users will be better off using the curl or curl_download function, or the http specific wrappers in the httr package.

Usage

curl_fetch_memory(url, handle = new_handle())
curl_fetch_disk(url, path, handle = new_handle())
curl_fetch_stream(url, fun, handle = new_handle())
curl_fetch_multi(url, done = NULL, fail = NULL, pool = NULL, handle = new_handle())

Arguments

url
A character string naming the URL of a resource to be downloaded.
handle
a curl handle object
path
Path to save results
fun
Callback function. Should have one argument, which will be a raw vector.
done
callback function for completed request. Single argument with response data in same structure as curl_fetch_memory.
fail
callback function called on failed request. Argument contains error message.
pool
a multi handle created by new_pool. Default uses a global pool.

Details

The curl_fetch functions automatically raise an error upon protocol problems (network, disk, ssl) but do not implement application logic. For example for you need to check the status code of http requests yourself in the response, and deal with it accordingly.

Both curl_fetch_memory and curl_fetch_disk have a blocking and non-blocking C implementation. The latter is slightly slower but allows for interrupting the download prematurely (using e.g. CTRL+C or ESC). Interrupting is enabled when R runs in interactive mode or when getOption("curl_interrupt") == TRUE.

The curl_fetch_multi function is the asyncronous equivalent of curl_fetch_memory. It wraps multi_add to schedule requests which are executed concurrently when calling multi_run. For each successful request the done callback is triggered with response data. For failed requests (when curl_fetch_memory would raise an error), the fail function is triggered with the error message.

Examples

Run this code
# Load in memory
res <- curl_fetch_memory("http://httpbin.org/cookies/set?foo=123&bar=ftw")
res$content

# Save to disk
res <- curl_fetch_disk("http://httpbin.org/stream/10", tempfile())
res$content
readLines(res$content)

# Stream with callback
res <- curl_fetch_stream("http://httpbin.org/stream/20", function(x){
  cat(rawToChar(x))
})

# Async API
data <- list()
success <- function(res){
  cat("Request done! Status:", res$status, "\n")
  data <<- c(data, list(res))
}
failure <- function(msg){
  cat("Oh noes! Request failed!", msg, "\n")
}
curl_fetch_multi("http://httpbin.org/get", success, failure)
curl_fetch_multi("http://httpbin.org/status/418", success, failure)
curl_fetch_multi("https://urldoesnotexist.xyz", success, failure)
multi_run()
str(data)

Run the code above in your browser using DataCamp Workspace