Debian Codegraph @

man/binaryBuffer.Rd

raw
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