File: postForm.html

package info (click to toggle)
r-cran-rcurl 1.95-4.8-2
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 4,140 kB
  • ctags: 515
  • sloc: ansic: 3,135; xml: 1,734; asm: 993; sh: 12; makefile: 2
file content (212 lines) | stat: -rw-r--r-- 7,106 bytes parent folder | download | duplicates (4)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>R: Submit an HTML form</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="R.css">
</head><body>

<table width="100%" summary="page for postForm"><tr><td>postForm</td><td align="right">R Documentation</td></tr></table>

<h2>Submit an HTML form</h2>

<h3>Description</h3>


<p>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.
</p>


<h3>Usage</h3>

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


<h3>Arguments</h3>


<table summary="R argblock">
<tr valign="top"><td><code>uri</code></td>
<td>
<p>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.</p>
</td></tr>
<tr valign="top"><td><code>...</code></td>
<td>
<p>the name-value pairs of parameters.
Note that these are not the CURL options.</p>
</td></tr>
<tr valign="top"><td><code>.params</code></td>
<td>
<p>instead of specifying the name-value parameters in
&quot;free&quot; form via the ... argument, one can specify them
as named list or character vector.
</p>
</td></tr>
<tr valign="top"><td><code>.opts</code></td>
<td>
<p>an object representing the CURL options for this call.</p>
</td></tr>
<tr valign="top"><td><code>curl</code></td>
<td>
<p>the <code>CURLHandle</code> object created earlier if one is
reusing these objects. Otherwise, a new one is generated and
discarded.</p>
</td></tr>
<tr valign="top"><td><code>style</code></td>
<td>
<p>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 <code>multipart/form-data</code>
transmission
and use 'post' for <code>application/x-www-form-urlencoded</code>
content.
This string is compared to the names
of (the internal) <code>PostStyles</code> vector using partial
matching.  In the future, we will use
enum values within R.
The default is <code>multipart/form-data</code> for reasons of backward compatability.
</p>
</td></tr>
<tr valign="top"><td><code>.encoding</code></td>
<td>
<p>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  &quot;utf-8&quot;,
or &quot;ISO-859-1&quot;.</p>
</td></tr>
<tr valign="top"><td><code>binary</code></td>
<td>
<p>a logical value indicating whether the caller  knows
whether the resulting content is binary (<code>TRUE</code>) or not
(<code>FALSE</code>) or unknown (<code>NA</code>).
</p>
</td></tr>  
<tr valign="top"><td><code>.checkParams</code></td>
<td>
<p>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 (in the way we would for <code>curlPerform</code>).
This check can lead to spurious warning messages if the form has parameters
with names that do conflict with Curl options. 
By specifying <code>FALSE</code> for this parameter, you can avoid this test
and hence any warnings. But make certain you know what you are doing.
</p>
</td></tr>
<tr valign="top"><td><code>.contentEncodeFun</code></td>
<td>
<p>a function which encodes strings in a
suitable manner.  For x-www-form-encoded submissions, this should 
most likely should be <code>curlPercentEncode</code> which maps spaces to
+, = to %3D, etc.
We are leaving the default as <code>curlEscape</code> for now until we test whether applications
continue to work with the correct encoding.</p>
</td></tr>
</table>


<h3>Details</h3>


<p>Creating a new <code>CURLHandle</code> 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.
</p>


<h3>Value</h3>


<p>By default, the text from the HTTP response is
returned.  
</p>


<h3>See Also</h3>


<p><code>getURL</code>
<code>curlOptions</code>
<code>curlSetOpt</code>
</p>


<h3>Examples</h3>

<pre>

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&amp;lr=&amp;ie=ISO-8859-1&amp;q=RCurl&amp;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.
if(url.exists("http://wwwx.cs.unc.edu/~jbs/aw-wwwp/docs/resources/perl/perl-cgi/programs/cgi_stdin.cgi")) 
 postForm("http://wwwx.cs.unc.edu/~jbs/aw-wwwp/docs/resources/perl/perl-cgi/programs/cgi_stdin.cgi",
           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"))
}
	  
</pre>


</body></html>