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               # Setting the options
34               my $curl = new WWW::Curl::Easy;
35
36               $curl->setopt(CURLOPT_HEADER,1);
37               $curl->setopt(CURLOPT_URL, 'http://example.com');
38               my $response_body;
39
40               # NOTE - do not use a typeglob here. A reference to a typeglob is okay though.
41               open (my $fileb, ">", \$response_body);
42               $curl->setopt(CURLOPT_WRITEDATA,$fileb);
43
44               # Starts the actual request
45               my $retcode = $curl->perform;
46
47               # Looking at the results...
48               if ($retcode == 0) {
49                       print("Transfer went ok\n");
50                       my $response_code = $curl->getinfo(CURLINFO_HTTP_CODE);
51                       # judge result and next action based on $response_code
52                       print("Received response: $response_body\n");
53               } else {
54                       print("An error happened: ".$curl->strerror($retcode)." ($retcode)\n");
55               }
56

WWW::Curl::Multi

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

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

COMPATIBILITY

156       curl_easy_setopt
157           Most of the options should work, however some might not. Please
158           send reports, tests and patches to fix those.
159
160       curl_easy_escape
161           Not implemented. Since equivalent Perl code is easily produced,
162           this method will only made available for interface completeness, if
163           ever.
164
165       curl_easy_init
166           Used only internally. The standard Perl way of initializing an
167           object should be used,
168            "my $curl = WWW::Curl::Easy->new;".
169
170       curl_easy_cleanup
171           Used only internally. Curl object cleanup happens when the handle
172           goes out of scope.
173
174       curl_easy_duphandle
175           Should be working for most cases, however do not change the value
176           of options which accept a list/arrayref value on a duped handle,
177           otherwise memory leaks or crashes will happen.  This behaviour will
178           be fixed in the future.
179
180       curl_easy_pause
181           Not implemented.
182
183       curl_easy_reset
184           Not implemented.
185
186       curl_easy_unescape
187           Not implemented. Trivial Perl replacements are available.
188
189       curl_escape
190           Not implemented and won't be as this method is considered
191           deprecated.
192
193       curl_formadd
194           Not yet implemented.
195
196       curl_formfree
197           When WWW::Curl::Form support is added, this function will be used
198           internally, but won't be accessible from the public API.
199
200       curl_free
201           Used internally. Not exposed through the public API, as this call
202           has no relevance to Perl code.
203
204       curl_getdate
205           Not implemented. This function is easily replaced by Perl code and
206           as such, most likely it won't be implemented.
207
208       curl_global_cleanup
209           Only used internally, not exposed through the public API.
210
211       curl_global_init
212           Only used internally, not exposed through the public API.
213
214       curl_global_init_mem
215           Not implemented.
216
217       curl_global_cleanup
218           Only used internally and called automatically upon exit.
219
220       curl_slist_append
221           Only used internally, not exposed through the public API.
222
223       curl_slist_free_all
224           Only used internally, not exposed through the public API.
225
226       curl_unescape
227           Not implemented and won't be, as this method is considered
228           deprecated.
229
230       curl_version_info
231           Not yet implemented.
232
233       curl_multi_*
234           Most methods are either not exposed through the WWW::Curl::Multi
235           API or they behave differently than it's C counterpart. Please see
236           the section about WWW::Curl::Multi above.
237

USAGE CASES

239       WWW::Curl is a thin binding on top of libcurl, to make using libcurl
240       possible from Perl land.  Because of this, the module is less like Perl
241       and more like C in coding style.
242
243       There is a new module,
244       <http://search.cpan.org/perldoc?WWW::Curl::Simple>, which wraps this
245       module into a more Perlish and userfriendly package.
246
247       The standard Perl WWW module, LWP should probably be used in most cases
248       to work with HTTP or FTP from Perl.  However, there are some cases
249       where LWP doesn't perform well. One is speed and the other is
250       parallelism.  WWW::Curl is much faster, uses much less CPU cycles and
251       it's capable of non-blocking parallel requests.
252
253       In some cases, for example when building a web crawler, cpu usage and
254       parallel downloads are important considerations. It can be desirable to
255       use WWW::Curl to do the heavy-lifting of a large number of downloads
256       and wrap the resulting data into a Perl-friendly structure by
257       HTTP::Response or use WWW::Curl::Simple to do that for you.
258

CHANGES

260       Version 4.01 - 4.07 adds several bugfixes and extends functionality
261       coverage. See Changes file.
262
263       Version 4.00 added new documentation, the build system changed to
264       Module::Install, the test suite was rewritten to use Test::More, a new
265       calling syntax for WWW::Curl::Multi was added, memory leak and other
266       bugfixes added, Perl 5.6 and libcurl 7.10.8 as minimum requirements for
267       this module were set.
268
269       Version 3.12 is a bugfix for a missing Share.pm.in file in the release.
270
271       Version 3.11 added WWW::Curl::Share.
272
273       Version 3.10 adds the WWW::Curl::Share interface by Anton Federov and
274       large file options after a contribution from Mark Hindley.
275
276       Version 3.02 adds some backwards compatibility for scripts still using
277       'WWW::Curl::easy' names.
278
279       Version 3.01 added some support for pre-multi versions of libcurl.
280
281       Version 3.00 adds WWW::Curl::Multi interface, and a new module names
282       following perl conventions (WWW::Curl::Easy rather than
283       WWW::Curl::easy), by Sebastian Riedel <sri at cpan.org>.
284
285       Version 2.00 of WWW::Curl::easy is a renaming of the previous version
286       (named Curl::easy), to follow CPAN naming guidelines, by Cris Bailiff.
287
288       Versions 1.30, a (hopefully) threadable, object-oriented, multiple-
289       callback compatible version of Curl::easy was substantially reworked
290       from the previous Curl::easy release (1.21) by Cris Bailiff.
291

AUTHORS

293       Currently maintained by Cris Bailiff <c.bailiff+curl at devsecure.com>
294       and Balint Szilakszi <szbalint at cpan.org>.
295
296       Original Author Georg Horn <horn@koblenz-net.de>, with additional
297       callback, pod and test work by Cris Bailiff
298       <c.bailiff+curl@devsecure.com> and Forrest Cahoon
299       <forrest.cahoon@merrillcorp.com>. Sebastian Riedel added ::Multi and
300       Anton Fedorov (datacompboy <at> mail.ru) added ::Share. Balint
301       Szilakszi repackaged the module into a more modern form.
302

COPYRIGHT

304       Copyright (C) 2000-2005,2008,2009 Daniel Stenberg, Cris Bailiff,
305       Sebastian Riedel, Balint Szilakszi et al.
306
307       You may opt to use, copy, modify, merge, publish, distribute and/or
308       sell copies of the Software, and permit persons to whom the Software is
309       furnished to do so, under the terms of the MPL or the MIT/X-derivate
310       licenses. You may pick one of these licenses.
311