nanonext (version 0.9.2)

ncurl_session: ncurl Session

Description

nano cURL - a minimalist http(s) client. A session encapsulates a connection, along with all related parameters, and may be used to return data multiple times by repeatedly calling transact, which transacts once over the connection.

Usage

ncurl_session(
  url,
  convert = TRUE,
  method = NULL,
  headers = NULL,
  data = NULL,
  response = NULL,
  timeout = NULL,
  tls = NULL
)
transact(session)

Value

For ncurl_session: an 'ncurlSession' object if successful, or else an 'errorValue'.

For transact: a named list of 4 elements:

• $status - integer HTTP repsonse status code (200 - OK). Use status_code for a translation of the meaning.

• $headers - named list of response headers (if specified in the session), or NULL otherwise. If the status code is within the 300 range, i.e. a redirect, the response header 'Location' is automatically appended to return the redirect address.

• $raw - raw vector of the received resource (use writeBin to save to a file).

• $data - converted character string (if specified in the session), or NULL otherwise. This may be further parsed this as html, json, xml etc. if required.

Arguments

url

the URL address.

convert

[default TRUE] logical value whether to attempt conversion of the received raw bytes to a character vector. Set to FALSE if downloading non-text data. Supplying a non-logical value will error.

method

(optional) the HTTP method (defaults to 'GET' if not specified).

headers

(optional) a named list or character vector specifying the HTTP request headers e.g. list(`Content-Type` = "text/plain") or c(Authorization = "Bearer APIKEY"). Supplying a non-named list or vector will error.

data

(optional) the request data to be submitted.

response

(optional) a character vector or list specifying the response headers to return e.g. c("date", "server") or list("Date", "Server"). These are case-insensitive and will return NULL if not present.

timeout

(optional) integer value in milliseconds after which the connection and subsequent transact attempts time out.

tls

(optional) applicable to secure HTTPS sites only, a client TLS Configuration object created by tls_config. If missing or NULL, certificates are not validated.

session

an 'ncurlSession' object.

Examples

s <- ncurl_session("https://www.r-project.org/", response = "date", timeout = 2000L)
s
if (!is_error_value(s)) transact(s)
if (!is_error_value(s)) close(s)