binaryBuffer              package:RCurl              R Documentation

_C_r_e_a_t_e _i_n_t_e_r_n_a_l _C-_l_e_v_e_l _d_a_t_a _s_t_r_u_c_t_u_r_e _f_o_r _c_o_l_l_e_c_t_i_n_g _b_i_n_a_r_y _d_a_t_a

_D_e_s_c_r_i_p_t_i_o_n:

     This is the constructor function for creating an internal data
     structure that is used when reading binary data from an HTTP
     request via RCurl.  It is used with the native routine
     'R_curl_write_binary_data' for collecting the response from the
     HTTP query into a buffer that stores the bytes. The contents can
     then be brought back into R as a 'raw' vector and then used in
     different ways, e.g. uncompressed with the 'Rcompression' package,
     or written to a file via 'writeBin'.

_U_s_a_g_e:

     binaryBuffer(initialSize = 5000)

_A_r_g_u_m_e_n_t_s:

initialSize: a number giving the size (number of bytes) to allocate for
          the buffer. In most cases, the size won't make an enormous
          difference. If this is small, the 'R_curl_write_binary_data'
          routine will expand it as necessary when more daat is
          received than would fit in it.  If it is very large, i.e.
          larger than the resulting response, the consequence is simply
          unused memory.   One can determine the appropriate size by
          performing the HTTP request with 'nobody = TRUE' and looking
          at the resulting size indicated by the headers of the
          response, i.e. 'getCurlInfo(handle)' and then using that size
          and repeating the request and receiving the body. This is a
          trade-off between network speed and memor consumption and
          processing speed when collecting the . 

_V_a_l_u_e:

     An object of class 'RCurlBinaryBuffer' which is to be treated as
     an opaque data for the most part. When passing this as the value
     of the 'file' option, one will have to pass the ref slot.

     After the contents have been read, one can convert this object to
     an R raw vector using 'as(buf, "raw")'.

_A_u_t_h_o_r(_s):

     Duncan Temple Lang <duncan@wald.ucdavis.edu>

_R_e_f_e_r_e_n_c_e_s:

     Curl homepage <URL: http://curl.haxx.se>

_S_e_e _A_l_s_o:

     'R_curl_write_binary_data'

_E_x_a_m_p_l_e_s:

       buf = binaryBuffer()

          # Now fetch the binary file.
       getURI("http://www.omegahat.org/RCurl/xmlParse.html.gz",
              write = getNativeSymbolInfo("R_curl_write_binary_data")$address,
              file = buf@ref)

        # Convert the internal data structure into an R raw vector
       b = as(buf, "raw")

      if(require(Rcompression)) 
        gunzip(b)

