| 1 |
\name{postForm} |
| 2 |
\alias{postForm} |
| 3 |
\alias{.postForm} |
| 4 |
\alias{getForm} |
| 5 |
\title{Submit an HTML form} |
| 6 |
\description{ |
| 7 |
These functions provide facilities for submitting an HTML |
| 8 |
form using either the simple GET mechanism (appending the name-value |
| 9 |
pairs of parameters in the URL) or the POST method which puts |
| 10 |
the name-value pairs as separate sections in the body of the |
| 11 |
HTTP request. The choice of action is defined by the form, |
| 12 |
not the caller. |
| 13 |
} |
| 14 |
\usage{ |
| 15 |
postForm(uri, ..., .params = list(), .opts = curlOptions(url = uri), |
| 16 |
curl = getCurlHandle(), style = 'HTTPPOST', |
| 17 |
.encoding = integer(), binary = NA, .checkParams = TRUE, |
| 18 |
.contentEncodeFun = curlEscape) |
| 19 |
.postForm(curl, .opts, .params, style = 'HTTPPOST') |
| 20 |
getForm(uri, ..., .params = character(), .opts = list(), curl = getCurlHandle(), |
| 21 |
.encoding = integer(), binary = NA, .checkParams = TRUE) |
| 22 |
} |
| 23 |
%- maybe also 'usage' for other objects documented here. |
| 24 |
\arguments{ |
| 25 |
\item{uri}{the full URI to which the form is to be posted. This |
| 26 |
includes the host and the specific file or script which will process |
| 27 |
the form.} |
| 28 |
\item{\dots}{the name-value pairs of parameters. |
| 29 |
Note that these are not the CURL options.} |
| 30 |
\item{.params}{instead of specifying the name-value parameters in |
| 31 |
"free" form via the \dots argument, one can specify them |
| 32 |
as named list or character vector. |
| 33 |
} |
| 34 |
\item{.opts}{an object representing the CURL options for this call.} |
| 35 |
\item{curl}{the \code{CURLHandle} object created earlier if one is |
| 36 |
reusing these objects. Otherwise, a new one is generated and |
| 37 |
discarded.} |
| 38 |
\item{style}{this is typically a string |
| 39 |
and controls how the form data is posted, specifically |
| 40 |
the value for the Content-Type header and the particular |
| 41 |
representation. |
| 42 |
Use 'httppost' to use a \code{multipart/form-data} |
| 43 |
transmission |
| 44 |
and use 'post' for \code{application/x-www-form-urlencoded} |
| 45 |
content. |
| 46 |
This string is compared to the names |
| 47 |
of (the internal) \code{PostStyles} vector using partial |
| 48 |
matching. In the future, we will use |
| 49 |
enum values within R. |
| 50 |
The default is \code{multipart/form-data} for reasons of backward compatability. |
| 51 |
} |
| 52 |
\item{.encoding}{the encoding of the result, if it is known a priori. |
| 53 |
This can be an integer between 0 and 4 or more appropriately a |
| 54 |
string identifying the encoding as one of "utf-8", |
| 55 |
or "ISO-859-1".} |
| 56 |
\item{binary}{a logical value indicating whether the caller knows |
| 57 |
whether the resulting content is binary (\code{TRUE}) or not |
| 58 |
(\code{FALSE}) or unknown (\code{NA}). |
| 59 |
} |
| 60 |
\item{.checkParams}{a logical value that indicates whether we should perform a check/test |
| 61 |
to identify if any of the arguments passed to the form correspond to Curl options. |
| 62 |
This is useful to identify potential errors in specifying the Curl options in the |
| 63 |
wrong place (in the way we would for \code{\link{curlPerform}}). |
| 64 |
This check can lead to spurious warning messages if the form has parameters |
| 65 |
with names that do conflict with Curl options. |
| 66 |
By specifying \code{FALSE} for this parameter, you can avoid this test |
| 67 |
and hence any warnings. But make certain you know what you are doing. |
| 68 |
} |
| 69 |
\item{.contentEncodeFun}{a function which encodes strings in a |
| 70 |
suitable manner. For x-www-form-encoded submissions, this should |
| 71 |
most likely should be \code{curlPercentEncode} which maps spaces to |
| 72 |
+, = to \%3D, etc. |
| 73 |
We are leaving the default as \code{curlEscape} for now until we test whether applications |
| 74 |
continue to work with the correct encoding.} |
| 75 |
} |
| 76 |
\details{ |
| 77 |
Creating a new \code{CURLHandle} allows the C-level code |
| 78 |
to more efficiently map the R-level values to their |
| 79 |
C equivalents needed to make the call. However, reusing |
| 80 |
the handle across calls can be more efficient in that |
| 81 |
the connection to a server can be maintained and thus, |
| 82 |
the sometimes expensive task of establishing it is |
| 83 |
avoided in subsequent calls. |
| 84 |
} |
| 85 |
\value{ |
| 86 |
By default, the text from the HTTP response is |
| 87 |
returned. |
| 88 |
} |
| 89 |
|
| 90 |
|
| 91 |
\seealso{ |
| 92 |
\code{\link{getURL}} |
| 93 |
\code{\link{curlOptions}} |
| 94 |
\code{\link{curlSetOpt}} |
| 95 |
} |
| 96 |
\examples{ |
| 97 |
|
| 98 |
if(url.exists("http://www.google.com")) withAutoprint({ |
| 99 |
# Two ways to submit a query to google. Searching for RCurl |
| 100 |
getURL("http://www.google.com/search?hl=en&lr=&ie=ISO-8859-1&q=RCurl&btnG=Search") |
| 101 |
|
| 102 |
# Here we let getForm do the hard work of combining the names and values. |
| 103 |
getForm("http://www.google.com/search", hl="en", lr="", |
| 104 |
ie="ISO-8859-1", q="RCurl", btnG="Search") |
| 105 |
|
| 106 |
# And here if we already have the parameters as a list/vector. |
| 107 |
getForm("http://www.google.com/search", .params = c(hl="en", lr="", |
| 108 |
ie="ISO-8859-1", q="RCurl", btnG="Search")) |
| 109 |
}) |
| 110 |
|
| 111 |
|
| 112 |
# Now looking at POST method for forms. |
| 113 |
url <- "http://wwwx.cs.unc.edu/~jbs/aw-wwwp/docs/resources/perl/perl-cgi/programs/cgi_stdin.cgi" |
| 114 |
if(url.exists(url)) |
| 115 |
postForm(url, |
| 116 |
name = "Bob", "checkedbox" = "spinich", |
| 117 |
submitButton = "Now!", |
| 118 |
textarea = "Some text to send", |
| 119 |
selectitem = "The item", |
| 120 |
radiobutton = "a", style = "POST") |
| 121 |
|
| 122 |
|
| 123 |
# Genetic database via the Web. |
| 124 |
if(url.exists('http://www.wormbase.org/db/searches/advanced/dumper')) withAutoprint({ |
| 125 |
x = postForm('http://www.wormbase.org/db/searches/advanced/dumper', |
| 126 |
species="briggsae", |
| 127 |
list="", |
| 128 |
flank3="0", |
| 129 |
flank5="0", |
| 130 |
feature="Gene Models", |
| 131 |
dump = "Plain TEXT", |
| 132 |
orientation = "Relative to feature", |
| 133 |
relative = "Chromsome", |
| 134 |
DNA ="flanking sequences only", |
| 135 |
.cgifields = paste(c("feature", "orientation", "DNA", "dump","relative"), collapse=", ")) |
| 136 |
|
| 137 |
|
| 138 |
# Note that we don't have to paste multiple values together ourselves, |
| 139 |
# e.g. the .cgifields can be specified as a character vector rather |
| 140 |
# than a string. |
| 141 |
x = postForm('http://www.wormbase.org/db/searches/advanced/dumper', |
| 142 |
species="briggsae", |
| 143 |
list="", |
| 144 |
flank3="0", |
| 145 |
flank5="0", |
| 146 |
feature="Gene Models", |
| 147 |
dump = "Plain TEXT", |
| 148 |
orientation = "Relative to feature", |
| 149 |
relative = "Chromsome", |
| 150 |
DNA ="flanking sequences only", |
| 151 |
.cgifields =c("feature", "orientation", "DNA", "dump", "relative")) |
| 152 |
}) |
| 153 |
|
| 154 |
} |
| 155 |
\keyword{IO} |
| 156 |
|
| 157 |
|