dynCurlReader             package:RCurl             R Documentation

_D_y_n_a_m_i_c_a_l_l_y _d_e_t_e_r_m_i_n_e _c_o_n_t_e_n_t-_t_y_p_e _o_f _b_o_d_y _f_r_o_m _H_T_T_P _h_e_a_d_e_r _a_n_d
_s_e_t _b_o_d_y _r_e_a_d_e_r

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

     This function is used for the 'writefunction' option in a curl
     HTTP request. The idea is that we read the header of the HTTP
     response and when our code determines that the header is complete
     (the presence of a blank line), it examines the contents of the
     header and finds a Content-Type field. It uses the value of this
     to determine the nature of the body of the HTTP response and
     dynamically (re)sets the reader for the curl handle appropriately.
     If the content is binary, it collects the content into a 'raw'
     vector; if it is text, it sets the appropriate character encoding
     and collects the content into a character vector.

     This function is like 'basicTextGatherer' but behaves dynamically
     by determining how to read the content based on the header of the
     HTTP response. This function returns a list of functions that are
     used to update and query a shared state across calls.

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

     dynCurlReader(curl = getCurlHandle(), txt = character(), max = NA, value = NULL, verbose = FALSE)

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

    curl: the curl handle to be used for the request. It is essential
          that this handle be used in the low-level call to
          'curlPerform' so that the update element sets the reader for
          the body on the appropriate curl handle that is used in the
          request. 

     txt: initial value of the text. This is almost always an empty
          character vector.

     max: the maximum number of characters to read. This is almost
          always 'NA'.

   value: a function that can be specified which will be used to
          convert the body of the response from text or raw in a
          customized manner, e.g. uncompress a gzip body. This can als
          be done explicitly with a call 'fun(reader$value())' after
          the body has been read. The advantage of specifying the
          function in the constructor of the reader  is that the
          end-user doesn't have to know which function to use to do the
          conversion. 

 verbose: a logical value indicating whether messages about progress
          and operations are written on the console as the header and
          body are processed. 

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

     A list with 5 elements all of which are functions. These are 

  update: the function that does the actual reading/processing of the
          content that libcurl passes to it from the header and the
          body. This is the work-horse of the reader.

   value: a function to get the body of the response

  header: a function to get the content of the HTPP header

   reset: a function to reset the internal contents which allows the
          same reader to be re-used in subsequent HTTP requests

    curl: accessor function for the curl handle specified in the call
          to create this dynamic reader object.


     This list has the S3 class vector 'c("DynamicRCurlTextHandler",
     "RCurlTextHandler", "RCurlCallbackFunction")'

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

     Duncan Temple Lang

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

     libcurl <URL: http://curl.haxx.se>

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

     'basicTextGatherer' 'curlPerform' 'getURLContent'

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

        # Each of these examples can be done with getURLContent().
        # These are here just to illustrate the dynamic reader.

       header = dynCurlReader()
       curlPerform(url = "http://www.omegahat.org/Rcartogram/demo.jpg", headerfunction = header$update, curl = header$curl())
       class( header$value() )
       length( header$value() )

          # gzip example.
       header = dynCurlReader()
       curlPerform(url = "http://www.omegahat.org/dd.gz", headerfunction = header$update, curl = header$curl())
       class( header$value() )
       length( header$value() )

       if(require(Rcompression))
          gunzip(header$value())

        # Character encoding example
     ## Not run: 
       header = dynCurlReader()
       curlPerform(url = "http://www.razorvine.net/test/utf8form/formaccepter.sn",
                    postfields = c(text = "ABC", outputencoding =  "UTF-8"),
                    verbose = TRUE,
                    writefunction = header$update, curl = header$curl())
       class( header$value() )
       Encoding( header$value() )
     ## End(Not run)

