RCurl (version 1.95-4.7)

postForm: Submit an HTML form

Description

These functions provide facilities for submitting an HTML form using either the simple GET mechanism (appending the name-value pairs of parameters in the URL) or the POST method which puts the name-value pairs as separate sections in the body of the HTTP request. The choice of action is defined by the form, not the caller.

Usage

postForm(uri, ..., .params = list(), .opts = curlOptions(url = uri),
         curl = getCurlHandle(), style = 'HTTPPOST',
          .encoding = integer(), binary = NA, .checkParams = TRUE,
          .contentEncodeFun = curlEscape)
.postForm(curl, .opts, .params, style = 'HTTPPOST')
getForm(uri, ..., .params = character(), .opts = list(), curl = getCurlHandle(),
         .encoding = integer(), binary = NA, .checkParams = TRUE)

Arguments

uri

the full URI to which the form is to be posted. This includes the host and the specific file or script which will process the form.

...

the name-value pairs of parameters. Note that these are not the CURL options.

.params

instead of specifying the name-value parameters in "free" form via the ...argument, one can specify them as named list or character vector.

.opts

an object representing the CURL options for this call.

curl

the CURLHandle object created earlier if one is reusing these objects. Otherwise, a new one is generated and discarded.

style

this is typically a string and controls how the form data is posted, specifically the value for the Content-Type header and the particular representation. Use 'httppost' to use a multipart/form-data transmission and us

.encoding

the encoding of the result, if it is known a priori. This can be an integer between 0 and 4 or more appropriately a string identifying the encoding as one of "utf-8", or "ISO-859-1".

binary

a logical value indicating whether the caller knows whether the resulting content is binary (TRUE) or not (FALSE) or unknown (NA).

.checkParams

a logical value that indicates whether we should perform a check/test to identify if any of the arguments passed to the form correspond to Curl options. This is useful to identify potential errors in specifying the Curl options in the wrong place

.contentEncodeFun

a function which encodes strings in a suitable manner. For x-www-form-encoded submissions, this should most likely should be curlPercentEncode which maps spaces to +, = to %3D, etc. We are leaving the default as curlEsca

Value

• By default, the text from the HTTP response is returned.

Details

Creating a new CURLHandle allows the C-level code to more efficiently map the R-level values to their C equivalents needed to make the call. However, reusing the handle across calls can be more efficient in that the connection to a server can be maintained and thus, the sometimes expensive task of establishing it is avoided in subsequent calls.

See Also

getURL curlOptions curlSetOpt

Examples

if(url.exists("http://www.google.com")) {
   # Two ways to submit a query to google. Searching for RCurl
  getURL("http://www.google.com/search?hl=en&lr=&ie=ISO-8859-1&q=RCurl&btnG=Search")

   # Here we let getForm do the hard work of combining the names and values.
  getForm("http://www.google.com/search", hl="en", lr="",
          ie="ISO-8859-1", q="RCurl", btnG="Search")

   # And here if we already have the parameters as a list/vector.
  getForm("http://www.google.com/search", .params = c(hl="en", lr="",
          ie="ISO-8859-1",  q="RCurl", btnG="Search"))
}


   # Now looking at POST method for forms.
url <- "http://wwwx.cs.unc.edu/~jbs/aw-wwwp/docs/resources/perl/perl-cgi/programs/cgi_stdin.cgi"
if(url.exists(url)) 
 postForm(url,
           name = "Bob", "checkedbox" = "spinich",
           submitButton = "Now!",
           textarea = "Some text to send",
           selectitem = "The item",
           radiobutton = "a", style = "POST")


  # Genetic database via the Web.
if(url.exists('http://www.wormbase.org/db/searches/advanced/dumper')) {
 x = postForm('http://www.wormbase.org/db/searches/advanced/dumper',
         species="briggsae",
         list="",
         flank3="0",
         flank5="0",
         feature="Gene Models",
         dump = "Plain TEXT",
         orientation = "Relative to feature",
         relative = "Chromsome",
         DNA ="flanking sequences only",
         .cgifields = paste(c("feature", "orientation", "DNA", "dump","relative"), collapse=", "))


 # Note that we don't have to paste multiple values together ourselves,
 # e.g. the .cgifields can be specified as a character vector rather
 # than a string.
 x = postForm('http://www.wormbase.org/db/searches/advanced/dumper',
         species="briggsae",
         list="",
         flank3="0",
         flank5="0",
         feature="Gene Models",
         dump = "Plain TEXT",
         orientation = "Relative to feature",
         relative = "Chromsome",
         DNA ="flanking sequences only",
         .cgifields =c("feature", "orientation", "DNA", "dump", "relative"))
}