curl_fetch_memory {curl} | R Documentation

## 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,
      data = NULL, handle = new_handle())

    curl_fetch_echo(url, 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.

`data`

(advanced) callback function, file path, or connection object for writing incoming data. This callback should only be used for streaming applications, where small pieces of incoming data get written before the request has completed. The signature for the callback function is `write(data, final = FALSE)`. If set to `NULL` the entire response gets buffered internally and returned by in the `done` callback (which is usually what you want).

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

    # 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://www.httpbin.org/drip?duration=5&numbytes=15&code=200", 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)

[Package curl version 3.3 Index]