Debian Codegraph @

man/postForm.Rd

raw
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