WWW::Curl(3pm)

1WWW::Curl(3)          User Contributed Perl Documentation         WWW::Curl(3)
2
3
4

NAME

6       WWW::Curl - Perl extension interface for libcurl
7

SYNOPSIS

9           use WWW::Curl;
10           print $WWW::Curl::VERSION;
11

DESCRIPTION

13       WWW::Curl is a Perl extension interface for libcurl.
14

DOCUMENTATION

16       This module provides a Perl interface to libcurl. It is not intended to
17       be a standalone module and because of this, the main libcurl
18       documentation should be consulted for API details at
19       <http://curl.haxx.se>. The documentation you're reading right now only
20       contains the Perl specific details, some sample code and the
21       differences between the C API and the Perl one.
22

WWW::Curl::Easy

24       The name might be confusing, it originates from libcurl. This is not an
25       ::Easy module in the sense normally used on CPAN.
26
27       Here is a small snippet of making a request with WWW::Curl::Easy.
28
29               use strict;
30               use warnings;
31               use WWW::Curl::Easy;
32
33               my $curl = WWW::Curl::Easy->new;
34
35               $curl->setopt(CURLOPT_HEADER,1);
36               $curl->setopt(CURLOPT_URL, 'http://example.com');
37
38               # A filehandle, reference to a scalar or reference to a typeglob can be used here.
39               my $response_body;
40               $curl->setopt(CURLOPT_WRITEDATA,\$response_body);
41
42               # Starts the actual request
43               my $retcode = $curl->perform;
44
45               # Looking at the results...
46               if ($retcode == 0) {
47                       print("Transfer went ok\n");
48                       my $response_code = $curl->getinfo(CURLINFO_HTTP_CODE);
49                       # judge result and next action based on $response_code
50                       print("Received response: $response_body\n");
51               } else {
52                       # Error code, type of error, error message
53                       print("An error happened: $retcode ".$curl->strerror($retcode)." ".$curl->errbuf."\n");
54               }
55
56       See curl_easy_setopt(3) for details of "setopt()".
57

WWW::Curl::Multi

59               use strict;
60               use warnings;
61               use WWW::Curl::Easy;
62               use WWW::Curl::Multi;
63
64               my %easy;
65               my $curl = WWW::Curl::Easy->new;
66               my $curl_id = '13'; # This should be a handle unique id.
67               $easy{$curl_id} = $curl;
68               my $active_handles = 0;
69
70               $curl->setopt(CURLOPT_PRIVATE,$curl_id);
71               # do the usual configuration on the handle
72               ...
73
74               my $curlm = WWW::Curl::Multi->new;
75
76               # Add some easy handles
77               $curlm->add_handle($curl);
78               $active_handles++;
79
80               while ($active_handles) {
81                       my $active_transfers = $curlm->perform;
82                       if ($active_transfers != $active_handles) {
83                               while (my ($id,$return_value) = $curlm->info_read) {
84                                       if ($id) {
85                                               $active_handles--;
86                                               my $actual_easy_handle = $easy{$id};
87                                               # do the usual result/error checking routine here
88                                               ...
89                                               # letting the curl handle get garbage collected, or we leak memory.
90                                               delete $easy{$id};
91                                       }
92                               }
93                       }
94               }
95
96       This interface is different than what the C API does. $curlm->perform
97       is non-blocking and performs requests in parallel. The method does a
98       little work and then returns control, therefor it has to be called
99       periodically to get the job done. It's return value is the number of
100       unfinished requests.
101
102       When the number of unfinished requests changes compared to the number
103       of active handles, $curlm->info_read should be checked for finished
104       requests. It returns one handle and it's return value at a time, or an
105       empty list if there are no more finished requests. $curlm->info_read
106       calls remove_handle on the given easy handle automatically, internally.
107       The easy handle will still remain available until it goes out of scope,
108       this action just detaches it from multi.
109
110       Please make sure that the easy handle does not get garbage collected
111       until after the multi handle finishes processing it, or bad things
112       happen.
113
114       The multi handle does not need to be cleaned up, when it goes out of
115       scope it calls the required cleanup methods automatically.
116
117       It is possible to use $curlm->add_handle to add further requests to be
118       processed after $curlm->perform has been called.  WWW::Curl::Multi
119       doesn't care about the order. It is possible to process all requests
120       for a multi handle and then add a new batch of easy handles for
121       processing.
122

124               use WWW::CURL::Share;
125               my $curlsh = new WWW::Curl::Share;
126               $curlsh->setopt(CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE);
127               $curlsh->setopt(CURLSHOPT_SHARE, CURL_LOCK_DATA_DNS);
128               $curl->setopt(CURLOPT_SHARE, $curlsh);
129               $curlsh->setopt(CURLSHOPT_UNSHARE, CURL_LOCK_DATA_COOKIE);
130               $curlsh->setopt(CURLSHOPT_UNSHARE, CURL_LOCK_DATA_DNS);
131
132       WWW::Curl::Share is an extension to WWW::Curl::Easy which makes it
133       possible to use a single cookies/dns cache for several Easy handles.
134
135       It's usable methods are:
136
137               $curlsh = new WWW::Curl::Share
138                       This method constructs a new WWW::Curl::Share object.
139
140               $curlsh->setopt(CURLSHOPT_SHARE, $value );
141                       Enables share for:
142                               CURL_LOCK_DATA_COOKIE   use single cookies database
143                               CURL_LOCK_DATA_DNS      use single DNS cache
144               $curlsh->setopt(CURLSHOPT_UNSHARE, $value );
145                       Disable share for given $value (see CURLSHOPT_SHARE)
146
147               $curlsh->strerror( ErrNo )
148                       This method returns a string describing the CURLSHcode error
149                       code passed in the argument errornum.
150
151       This is how you enable sharing for a specific WWW::Curl::Easy handle:
152
153               $curl->setopt(CURLOPT_SHARE, $curlsh)
154                       Attach share object to WWW::Curl::Easy instance
155

WWW::Curl::Form

157           use WWW::Curl::Form;
158           my $curlf = WWW::Curl::Form->new;
159           $curlf->formaddfile($filename, 'attachment', "multipart/form-data");
160           $curlf->formadd("FIELDNAME", "VALUE");
161
162           $curl->setopt(CURLOPT_HTTPPOST, $curlf);
163
164       Its usable methods are:
165
166           $curlf = new WWW::Curl::Form
167               This method constructs a new WWW::Curl::Form object.
168
169           $curlf->formadd(FIELDNAME, VALUE)
170               This method adds a field with a given value, to the form that is being submitted.
171
172           $curlf->formaddfile(FILENAME, DESCRIPTION, TYPE)
173               This method will add a file to the form. The description is the name of the field
174               that you form expects the data to be submitted in.
175

COMPATIBILITY

177       curl_easy_setopt
178           Most of the options should work, however some might not. Please
179           send reports, tests and patches to fix those.
180
181       curl_easy_escape
182           Not implemented. Since equivalent Perl code is easily produced,
183           this method will only made available for interface completeness, if
184           ever.
185
186       curl_easy_init
187           Used only internally. The standard Perl way of initializing an
188           object should be used,
189            "my $curl = WWW::Curl::Easy->new;".
190
191       curl_easy_cleanup
192           Used only internally. Curl object cleanup happens when the handle
193           goes out of scope.
194
195       curl_easy_duphandle
196           Should be working for most cases, however do not change the value
197           of options which accept a list/arrayref value on a duped handle,
198           otherwise memory leaks or crashes will happen.  This behaviour will
199           be fixed in the future.
200
201       curl_easy_pause
202           Not implemented.
203
204       curl_easy_reset
205           Not implemented.
206
207       curl_easy_unescape
208           Not implemented. Trivial Perl replacements are available.
209
210       curl_escape
211           Not implemented and won't be as this method is considered
212           deprecated.
213
214       curl_formadd
215           Seems to be working.
216
217       curl_formaddfile
218           Seems to be working.
219
220       curl_formfree
221           Used internally. Not exposed through the public API, as this call
222           has no relevance to Perl code.
223
224       curl_free
225           Used internally. Not exposed through the public API, as this call
226           has no relevance to Perl code.
227
228       curl_getdate
229           Not implemented. This function is easily replaced by Perl code and
230           as such, most likely it won't be implemented.
231
232       curl_global_cleanup
233           Only used internally, not exposed through the public API.
234
235       curl_global_init
236           Only used internally, not exposed through the public API.
237
238       curl_global_init_mem
239           Not implemented.
240
241       curl_global_cleanup
242           Only used internally and called automatically upon exit.
243
244       curl_slist_append
245           Only used internally, not exposed through the public API.
246
247       curl_slist_free_all
248           Only used internally, not exposed through the public API.
249
250       curl_unescape
251           Not implemented and won't be, as this method is considered
252           deprecated.
253
254       curl_version
255           Seems to work.
256
257       curl_version_info
258           Not yet implemented.
259
260       curl_multi_*
261           Most methods are either not exposed through the WWW::Curl::Multi
262           API or they behave differently than it's C counterpart. Please see
263           the section about WWW::Curl::Multi above.
264
265       curl_multi_fdset
266           This method returns three arrayrefs: the read, write and exception
267           fds libcurl knows about.  In the case of no file descriptors in the
268           given set, an empty array is returned.
269

NUANCES

271   Header output for redirects
272       It might be surprising that if "CURLOPT_FOLLOWLOCATION" is set and
273       header output was enabled, headers show up for all http responses.  The
274       reasoning behind that and possible code adjustments are outlined here:
275       <https://rt.cpan.org/Ticket/Display.html?id=61569>.
276
277   CURLOPT_PRIVATE
278       Despite what the libcurl manual says, in Perl land, only string values
279       are suitable for this option.
280

ADDITIONAL METHODS

282   On WWW::Curl::Easy objects
283       pushopt
284           Like "setopt" but instead of overriding any previously set values
285           it adds it to the end. Can be used with "CURLOPT_HTTPHEADER",
286           "CURLOPT_QUOTE" and "CURLOPT_POSTQUOTE".
287

USAGE CASES

289       WWW::Curl is a thin binding on top of libcurl, to make using libcurl
290       possible from Perl land.  Because of this, the module is less like Perl
291       and more like C in coding style.
292
293       There is a new module,
294       <http://search.cpan.org/perldoc?WWW::Curl::Simple>, which wraps this
295       module into a more Perlish and userfriendly package.
296
297       The standard Perl WWW module, LWP should probably be used in most cases
298       to work with HTTP or FTP from Perl.  However, there are some cases
299       where LWP doesn't perform well. One is speed and the other is
300       parallelism.  WWW::Curl is much faster, uses much less CPU cycles and
301       it's capable of non-blocking parallel requests.
302
303       In some cases, for example when building a web crawler, cpu usage and
304       parallel downloads are important considerations. It can be desirable to
305       use WWW::Curl to do the heavy-lifting of a large number of downloads
306       and wrap the resulting data into a Perl-friendly structure by
307       HTTP::Response or use WWW::Curl::Simple to do that for you.
308

CHANGES

310       Version 4.01 - 4.07 adds several bugfixes and extends functionality
311       coverage. See Changes file.
312
313       Version 4.00 added new documentation, the build system changed to
314       Module::Install, the test suite was rewritten to use Test::More, a new
315       calling syntax for WWW::Curl::Multi was added, memory leak and other
316       bugfixes added, Perl 5.6 and libcurl 7.10.8 as minimum requirements for
317       this module were set.
318
319       Version 3.12 is a bugfix for a missing Share.pm.in file in the release.
320
321       Version 3.11 added WWW::Curl::Share.
322
323       Version 3.10 adds the WWW::Curl::Share interface by Anton Federov and
324       large file options after a contribution from Mark Hindley.
325
326       Version 3.02 adds some backwards compatibility for scripts still using
327       'WWW::Curl::easy' names.
328
329       Version 3.01 added some support for pre-multi versions of libcurl.
330
331       Version 3.00 adds WWW::Curl::Multi interface, and new module names
332       following perl conventions (WWW::Curl::Easy rather than
333       WWW::Curl::easy), by Sebastian Riedel <sri at cpan.org>.
334
335       Version 2.00 of WWW::Curl::easy is a renaming of the previous version
336       (named Curl::easy), to follow CPAN naming guidelines, by Cris Bailiff.
337
338       Versions 1.30, a (hopefully) threadable, object-oriented, multiple-
339       callback compatible version of Curl::easy was substantially reworked
340       from the previous Curl::easy release (1.21) by Cris Bailiff.
341

AUTHORS

343       Currently maintained by Cris Bailiff <c.bailiff+curl at devsecure.com>
344       and Balint Szilakszi <szbalint at cpan.org>.
345
346       Original Author Georg Horn <horn@koblenz-net.de>, with additional
347       callback, pod and test work by Cris Bailiff
348       <c.bailiff+curl@devsecure.com> and Forrest Cahoon
349       <forrest.cahoon@merrillcorp.com>. Sebastian Riedel added ::Multi and
350       Anton Fedorov (datacompboy <at> mail.ru) added ::Share. Balint
351       Szilakszi repackaged the module into a more modern form.
352

COPYRIGHT

354       Copyright (C) 2000-2005,2008-2010 Daniel Stenberg, Cris Bailiff,
355       Sebastian Riedel, Balint Szilakszi et al.
356
357       You may opt to use, copy, modify, merge, publish, distribute and/or
358       sell copies of the Software, and permit persons to whom the Software is
359       furnished to do so, under the terms of the MPL or the MIT/X-derivate
360       licenses. You may pick one of these licenses.
361