| 1 |
\name{fileUpload} |
| 2 |
\alias{fileUpload} |
| 3 |
\title{Specify information about a file to upload in an HTTP request} |
| 4 |
\description{ |
| 5 |
This function creates an object that describes all of the details |
| 6 |
needed to include the contents of a file in the submission of an |
| 7 |
HTTP request, typically a multi-part form submitted via |
| 8 |
\code{\link{postForm}}. |
| 9 |
The idea is that we want to transfer the contents of a file or a |
| 10 |
buffer of data within R that is not actually stored on the file |
| 11 |
system but is resident in the R session. We want to be able to |
| 12 |
specify either the name of the file and have RCurl read the contents |
| 13 |
when they are needed, or alternatively specify the contents ourselves |
| 14 |
if it makes sense that we already have the contents in R, e.g. that |
| 15 |
they are dynamically generated. Additionally, we may need to specify |
| 16 |
the type of data in the file/buffer via the Content-Type field for |
| 17 |
this parameter in the request. |
| 18 |
This function allows us to specify either the file name or contents |
| 19 |
and optionally the content type. |
| 20 |
|
| 21 |
This is used as an element in of the \code{params} argument |
| 22 |
\code{\link{postForm}} and the native C code understands and processes |
| 23 |
objects returned from this function. |
| 24 |
|
| 25 |
} |
| 26 |
\usage{ |
| 27 |
fileUpload(filename = character(), contents = character(), contentType = character()) |
| 28 |
} |
| 29 |
%- maybe also 'usage' for other objects documented here. |
| 30 |
\arguments{ |
| 31 |
\item{filename}{the name of the file that RCurl is to pass in the form |
| 32 |
submission/HTTP request. If this is specified and no value for |
| 33 |
\code{contents} is given, this has to identify a valid/existing |
| 34 |
file. If \code{contents} is specified, any value provided here |
| 35 |
is used simply to provide information about the provenance of the |
| 36 |
data in contents. The file need not exist. |
| 37 |
The path is expanded by the function, so \code{~} can be used. |
| 38 |
} |
| 39 |
\item{contents}{ either a character vector or a \code{raw} vector |
| 40 |
giving the contents or data to be submitted. If this is provided, |
| 41 |
\code{filename} is not needed and not read. |
| 42 |
} |
| 43 |
\item{contentType}{a character string (vector of length 1) giving the |
| 44 |
type of the content, e.g. text/plain, text/html, which helps the |
| 45 |
server receiving the data to interpret the contents. If omitted, |
| 46 |
this is omitted from the form submission and the recipient left to guess. |
| 47 |
} |
| 48 |
} |
| 49 |
\value{ |
| 50 |
An object of (S3) class \code{FileUploadInfo} with fields |
| 51 |
\code{filename}, \code{contents} and \code{contentType}. |
| 52 |
} |
| 53 |
|
| 54 |
\references{ |
| 55 |
\url{https://curl.se/} |
| 56 |
} |
| 57 |
\author{Duncan Temple Lang} |
| 58 |
\seealso{ |
| 59 |
\code{\link{postForm}} |
| 60 |
} |
| 61 |
%\examples{} |
| 62 |
\keyword{IO} |