% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ncurl.R
\name{ncurl_session}
\alias{ncurl_session}
\alias{transact}
\title{ncurl Session}
\usage{
ncurl_session(
  url,
  convert = TRUE,
  method = NULL,
  headers = NULL,
  data = NULL,
  response = NULL,
  timeout = NULL,
  tls = NULL
)

transact(session)
}
\arguments{
\item{url}{the URL address.}

\item{convert}{[default TRUE] logical value whether to attempt conversion
of the received raw bytes to a character vector. Set to \code{FALSE} if
downloading non-text data.}

\item{method}{(optional) the HTTP method as a character string. Defaults to
'GET' if not specified, and could also be 'POST', 'PUT' etc.}

\item{headers}{(optional) a named character vector specifying the HTTP
request headers, for example: \cr
\code{c(Authorization = "Bearer APIKEY", "Content-Type" = "text/plain")} \cr
A non-character or non-named vector will be ignored.}

\item{data}{(optional) request data to be submitted. Must be a character
string or raw vector, and other objects are ignored. If a character vector,
only the first element is taken. When supplying binary data, the
appropriate 'Content-Type' header should be set to specify the binary
format.}

\item{response}{(optional) a character vector specifying the response headers
to return e.g. \code{c("date", "server")}. These are case-insensitive and
will return NULL if not present. Specify \code{TRUE} to return all response
headers. A non-character vector will be ignored (other than \code{TRUE}).}

\item{timeout}{(optional) integer value in milliseconds after which the
connection and subsequent transact attempts time out.}

\item{tls}{(optional) applicable to secure HTTPS sites only, a client TLS
Configuration object created by \code{\link[=tls_config]{tls_config()}}. If missing or NULL,
certificates are not validated.}

\item{session}{an 'ncurlSession' object.}
}
\value{
For \code{ncurl_session}: an 'ncurlSession' object if successful, or else
an 'errorValue'.

For \code{transact}: a named list of 3 elements:
\itemize{
\item \verb{$status} - integer HTTP repsonse status code (200 - OK). Use
\code{\link[=status_code]{status_code()}} for a translation of the meaning.
\item \verb{$headers} - named list of response headers (all headers if
\code{response = TRUE} was specified for the session, those specified in
\code{response}, or NULL otherwise).
\item \verb{$data} - the response body as a character string (if \code{convert = TRUE} was
specified for the session), which may be further parsed as html, json, xml
etc. as required, or else a raw byte vector, which may be saved as a file
using \code{\link[=writeBin]{writeBin()}}.
}
}
\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 \code{transact()}, which transacts once over the
connection.
}
\section{Public Internet HTTPS}{


When making HTTPS requests over the public internet, you should supply a TLS
configuration to validate server certificates. See \code{\link[=tls_config]{tls_config()}} for
details.
}

\examples{
s <- ncurl_session(
  "https://postman-echo.com/get",
  response = "date",
  timeout = 2000L
)
s
if (is_ncurl_session(s)) transact(s)
if (is_ncurl_session(s)) close(s)

}
\seealso{
\code{\link[=ncurl]{ncurl()}} for synchronous http requests; \code{\link[=ncurl_aio]{ncurl_aio()}} for
asynchronous http requests.
}
