| 1 |
\name{binaryBuffer} |
| 2 |
\alias{binaryBuffer} |
| 3 |
\alias{coerce,RCurlBinaryBuffer,raw-method} |
| 4 |
\title{Create internal C-level data structure for collecting binary data} |
| 5 |
\description{ |
| 6 |
This is the constructor function for creating an internal data |
| 7 |
structure |
| 8 |
that is used when reading binary data from an HTTP request |
| 9 |
via RCurl. It is used with the native routine |
| 10 |
\code{R_curl_write_binary_data} for collecting |
| 11 |
the response from the HTTP query into a buffer that stores |
| 12 |
the bytes. The contents can then be brought back into R |
| 13 |
as a \code{raw} vector and then used in different ways, |
| 14 |
e.g. uncompressed with the \code{Rcompression} package, |
| 15 |
or written to a file via \code{\link[base]{writeBin}}. |
| 16 |
} |
| 17 |
\usage{ |
| 18 |
binaryBuffer(initialSize = 5000) |
| 19 |
} |
| 20 |
\arguments{ |
| 21 |
\item{initialSize}{a number giving the size (number of bytes) to |
| 22 |
allocate for the buffer. In most cases, the size won't make an |
| 23 |
enormous difference. If this is small, the |
| 24 |
\code{R_curl_write_binary_data} routine will expand it as necessary |
| 25 |
when more daat is received than would fit in it. If it is very |
| 26 |
large, i.e. larger than the resulting response, the consequence is |
| 27 |
simply unused memory. One can determine the appropriate size by |
| 28 |
performing the HTTP request with \code{nobody = TRUE} and looking |
| 29 |
at the resulting size indicated by the headers of the response, |
| 30 |
i.e. |
| 31 |
\code{getCurlInfo(handle)} and then using that size and repeating |
| 32 |
the request and receiving the body. This is a trade-off between |
| 33 |
network speed and memor consumption and processing speed when |
| 34 |
collecting the . |
| 35 |
} |
| 36 |
} |
| 37 |
|
| 38 |
\value{ |
| 39 |
An object of class \code{RCurlBinaryBuffer} which is to be treated |
| 40 |
as an opaque data for the most part. When passing this as the value of |
| 41 |
the \code{file} option, one will have to pass the ref slot. |
| 42 |
|
| 43 |
After the contents have been read, one can convert this object to an R |
| 44 |
raw vector using \code{as(buf, "raw")}. |
| 45 |
} |
| 46 |
\references{Curl homepage \url{https://curl.se/}} |
| 47 |
\author{Duncan Temple Lang} |
| 48 |
|
| 49 |
\seealso{ |
| 50 |
\code{R_curl_write_binary_data} |
| 51 |
} |
| 52 |
\examples{ |
| 53 |
tryCatch(withAutoprint({ |
| 54 |
buf = binaryBuffer() |
| 55 |
|
| 56 |
# Now fetch the binary file. |
| 57 |
getURI("https://aitap.grebedoc.dev/RCurl/xmlParse.html.gz", |
| 58 |
write = getNativeSymbolInfo("R_curl_write_binary_data")$address, |
| 59 |
file = buf@ref) |
| 60 |
|
| 61 |
# Convert the internal data structure into an R raw vector |
| 62 |
b = as(buf, "raw") |
| 63 |
|
| 64 |
if (getRversion() >= "4") |
| 65 |
txt = memDecompress(b, asChar = TRUE) |
| 66 |
## or txt = Rcompression::gunzip(b) |
| 67 |
}), GenericCurlError = identity) |
| 68 |
} |
| 69 |
\keyword{IO} |
| 70 |
\keyword{programming} |
| 71 |
\concept{Web} |
| 72 |
\concept{binary data} |
| 73 |
|