Class: Curl::Easy

Inherits:
Object
  • Object
show all
Defined in:
lib/curb.rb,
ext/curb_easy.c

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.download(url, filename = url.split(/\?/).first.split(/\//).last, &blk) ⇒ Object

call-seq:

Curl::Easy.download(url, filename = url.split(/\?/).first.split(/\//).last) { |curl| ... }

Stream the specified url (via perform) and save the data directly to the supplied filename (defaults to the last component of the URL path, which will usually be the filename most simple urls).

If a block is supplied, it will be passed the curl instance prior to the perform call.

Note that the semantics of the on_body handler are subtly changed when using download, to account for the automatic routing of data to the specified file: The data string is passed to the handler before it is written to the file, allowing the handler to perform mutative operations where necessary. As usual, the transfer will be aborted if the on_body handler returns a size that differs from the data chunk size - in this case, the offending chunk will not be written to the file, the file will be closed, and a Curl::Err::AbortedByCallbackError will be raised.



25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/curb.rb', line 25

def download(url, filename = url.split(/\?/).first.split(/\//).last, &blk)
  curl = Curl::Easy.new(url, &blk)
  
  File.open(filename, "wb") do |output|
    old_on_body = curl.on_body do |data| 
      result = old_on_body ?  old_on_body.call(data) : data.length
      output << data if result == data.length
      result
    end
    
    curl.perform
  end        

  return curl
end

.Curl::Easy.http_delete(url) {|easy| ... } ⇒ #<Curl::Easy...>

Convenience method that creates a new Curl::Easy instance with the specified URL and calls http_delete, before returning the new instance.

If a block is supplied, the new instance will be yielded just prior to the http_delete call.

Yields:

  • (easy)

Returns:



2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
 
# File 'ext/curb_easy.c', line 2674

static VALUE ruby_curl_easy_class_perform_delete(int argc, VALUE *argv, VALUE klass) {
  VALUE c = ruby_curl_easy_new(argc, argv, klass);

  if (rb_block_given_p()) {
    rb_yield(c);
  }

  ruby_curl_easy_perform_delete(c);
  return c;
}

.Curl::Easy.http_get(url) {|easy| ... } ⇒ #<Curl::Easy...>

Convenience method that creates a new Curl::Easy instance with the specified URL and calls http_get, before returning the new instance.

If a block is supplied, the new instance will be yielded just prior to the http_get call.

Yields:

  • (easy)

Returns:



2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
 
# File 'ext/curb_easy.c', line 2653

static VALUE ruby_curl_easy_class_perform_get(int argc, VALUE *argv, VALUE klass) {
  VALUE c = ruby_curl_easy_new(argc, argv, klass);

  if (rb_block_given_p()) {
    rb_yield(c);
  }

  ruby_curl_easy_perform_get(c);
  return c;
}

.Curl::Easy.http_head(url) {|easy| ... } ⇒ #<Curl::Easy...>

Convenience method that creates a new Curl::Easy instance with the specified URL and calls http_head, before returning the new instance.

If a block is supplied, the new instance will be yielded just prior to the http_head call.

Yields:

  • (easy)

Returns:



2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
 
# File 'ext/curb_easy.c', line 2695

static VALUE ruby_curl_easy_class_perform_head(int argc, VALUE *argv, VALUE klass) {
  VALUE c = ruby_curl_easy_new(argc, argv, klass);

  if (rb_block_given_p()) {
    rb_yield(c);
  }

  ruby_curl_easy_perform_head(c);

  return c;
}

.Curl::Easy.http_post(url, "some = urlencoded%20form%20data&and=so%20on") ⇒ true .Curl::Easy.http_post(url, "some = urlencoded%20form%20data", "and = so%20on", ...) ⇒ true .Curl::Easy.http_post(url, "some = urlencoded%20form%20data", Curl: :PostField, "and = so%20on", ...) ⇒ true .Curl::Easy.http_post(url, Curl: :PostField, Curl: :PostField..., Curl: :PostField) ⇒ true

POST the specified formdata to the currently configured URL using the current options set for this Curl::Easy instance. This method always returns true, or raises an exception (defined under Curl::Err) on error.

If you wish to use multipart form encoding, you’ll need to supply a block in order to set multipart_form_post true. See #http_post for more information.

Overloads:

  • .Curl::Easy.http_post(url, "some = urlencoded%20form%20data&and=so%20on") ⇒ true

    Returns:

    • (true)
  • .Curl::Easy.http_post(url, "some = urlencoded%20form%20data", "and = so%20on", ...) ⇒ true

    Returns:

    • (true)
  • .Curl::Easy.http_post(url, "some = urlencoded%20form%20data", Curl: :PostField, "and = so%20on", ...) ⇒ true

    Returns:

    • (true)
  • .Curl::Easy.http_post(url, Curl: :PostField, Curl: :PostField..., Curl: :PostField) ⇒ true

    Returns:

    • (true) 


2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
 
# File 'ext/curb_easy.c', line 2725

static VALUE ruby_curl_easy_class_perform_post(int argc, VALUE *argv, VALUE klass) {
  VALUE url, fields;

  rb_scan_args(argc, argv, "1*", &url, &fields);

  VALUE c = ruby_curl_easy_new(1, &url, klass);

  if (argc > 1) {
    ruby_curl_easy_perform_post(argc - 1, &argv[1], c);
  } else {
    ruby_curl_easy_perform_post(0, NULL, c);
  }

  return c;
}

.Curl::Easy.new ⇒ #<Curl::Easy...> .Curl::Easy.new(url = nil) ⇒ #<Curl::Easy...> .Curl::Easy.new(url = nil) {|self| ... } ⇒ #<Curl::Easy...>

Create a new Curl::Easy instance, optionally supplying the URL. The block form allows further configuration to be supplied before the instance is returned.

Overloads:



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'ext/curb_easy.c', line 191

static VALUE ruby_curl_easy_new(int argc, VALUE *argv, VALUE klass) {
  CURLcode ecode;
  VALUE url, blk;
  VALUE new_curl;

  rb_scan_args(argc, argv, "01&", &url, &blk);

  ruby_curl_easy *rbce = ALLOC(ruby_curl_easy);

  /* handler */
  rbce->curl = curl_easy_init();

  /* assoc objects */
  rbce->url = url;
  rbce->proxy_url = Qnil;
  rbce->body_data = Qnil;
  rbce->body_proc = Qnil;
  rbce->header_data = Qnil;
  rbce->header_proc = Qnil;
  rbce->progress_proc = Qnil;
  rbce->debug_proc = Qnil;
  rbce->interface = Qnil;
  rbce->userpwd = Qnil;
  rbce->proxypwd = Qnil;
  rbce->headers = rb_hash_new();
  rbce->cookies = Qnil;
  rbce->cookiefile = Qnil;
  rbce->cookiejar = Qnil;
  rbce->cert = Qnil;
  rbce->cacert = Qnil;
  rbce->certpassword = Qnil;
  rbce->certtype = rb_str_new2("PEM");
  rbce->encoding = Qnil;
  rbce->useragent = Qnil;
  rbce->success_proc = Qnil;
  rbce->failure_proc = Qnil;
  rbce->complete_proc = Qnil;

  /* various-typed opts */
  rbce->local_port = 0;
  rbce->local_port_range = 0;
  rbce->proxy_port = 0;
  rbce->proxy_type = -1;
  rbce->http_auth_types = 0;
  rbce->proxy_auth_types = 0;
  rbce->max_redirs = -1;
  rbce->timeout = 0;
  rbce->connect_timeout = 0;
  rbce->dns_cache_timeout = 60;
  rbce->ftp_response_timeout = 0;

  /* bool opts */
  rbce->proxy_tunnel = 0;
  rbce->fetch_file_time = 0;
  rbce->ssl_verify_peer = 1;
  rbce->ssl_verify_host = 1;
  rbce->header_in_body = 0;
  rbce->use_netrc = 0;
  rbce->follow_location = 0;
  rbce->unrestricted_auth = 0;
  rbce->verbose = 0;
  rbce->multipart_form_post = 0;
  rbce->enable_cookies = 0;

  /* buffers */
  rbce->postdata_buffer = Qnil;
  rbce->bodybuf = Qnil;
  rbce->headerbuf = Qnil;
  rbce->curl_headers = NULL;

  rbce->self = Qnil;
  rbce->upload = Qnil;

  new_curl = Data_Wrap_Struct(klass, curl_easy_mark, curl_easy_free, rbce);

  if (blk != Qnil) {
    rb_funcall(blk, idCall, 1, new_curl);
  }

  /* set the rbce pointer to the curl handle */
  ecode = curl_easy_setopt(rbce->curl, CURLOPT_PRIVATE, (void*)rbce);
  if (ecode != CURLE_OK) {
    raise_curl_easy_error_exception(ecode);
  }

  return new_curl;
}

.Curl::Easy.perform(url) {|easy| ... } ⇒ #<Curl::Easy...>

Convenience method that creates a new Curl::Easy instance with the specified URL and calls the general perform method, before returning the new instance. For HTTP URLs, this is equivalent to calling http_get.

If a block is supplied, the new instance will be yielded just prior to the http_get call.

Yields:

  • (easy)

Returns:



2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
 
# File 'ext/curb_easy.c', line 2632

static VALUE ruby_curl_easy_class_perform(int argc, VALUE *argv, VALUE klass) {
  VALUE c = ruby_curl_easy_new(argc, argv, klass);

  if (rb_block_given_p()) {
    rb_yield(c);
  }

  ruby_curl_easy_perform(c);
  return c;
}

Instance Method Details

#body_str ⇒ Object

Return the response body from the previous call to perform. This is populated by the default on_body handler - if you supply your own body handler, this string will be empty.



1994
1995
1996
 
# File 'ext/curb_easy.c', line 1994

static VALUE ruby_curl_easy_body_str_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, body_data);
}

#cacert ⇒ Object

Obtain the cacert file to use for this Curl::Easy instance.



578
579
580
 
# File 'ext/curb_easy.c', line 578

static VALUE ruby_curl_easy_cacert_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, cacert);
}

#cacert=(cacert) ⇒ Object

Set a cacert bundle to use for this Curl::Easy instance. This file will be used to validate SSL certificates.



568
569
570
 
# File 'ext/curb_easy.c', line 568

static VALUE ruby_curl_easy_cacert_set(VALUE self, VALUE cacert) {
  CURB_OBJECT_SETTER(ruby_curl_easy, cacert);
}

#cert ⇒ Object

Obtain the cert file to use for this Curl::Easy instance.



556
557
558
 
# File 'ext/curb_easy.c', line 556

static VALUE ruby_curl_easy_cert_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, cert);
}

#cert=(cert) ⇒ Object

Set a cert file to use for this Curl::Easy instance. This file will be used to validate SSL connections.



546
547
548
549
550
551
552
553
554
555
 
# File 'ext/curb_easy.c', line 546

def cert=(cert_file)
  pos = cert_file.rindex(':')
  if pos && pos > 1
    self.native_cert= cert_file[0..pos-1]
    self.certpassword= cert_file[pos+1..-1]
  else
    self.native_cert= cert_file
  end
  self.cert
end

#certpassword=(certpassword) ⇒ Object

Set a password used to open the specified cert



588
589
590
 
# File 'ext/curb_easy.c', line 588

static VALUE ruby_curl_easy_certpassword_set(VALUE self, VALUE certpassword) {
  CURB_OBJECT_SETTER(ruby_curl_easy, certpassword);
}

#certtype ⇒ Object

Obtain the cert type used for this Curl::Easy instance



610
611
612
 
# File 'ext/curb_easy.c', line 610

static VALUE ruby_curl_easy_certtype_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, certtype);
}

#certtype=(certtype) ⇒ Object

Set a cert type to use for this Curl::Easy instance. Default is PEM



600
601
602
 
# File 'ext/curb_easy.c', line 600

static VALUE ruby_curl_easy_certtype_set(VALUE self, VALUE certtype) {
  CURB_OBJECT_SETTER(ruby_curl_easy, certtype);
}

#clone ⇒ Object #dup ⇒ Object Also known as: dup

Clone this Curl::Easy instance, creating a new instance. This method duplicates the underlying CURL* handle.



287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'ext/curb_easy.c', line 287

static VALUE ruby_curl_easy_clone(VALUE self) {
  ruby_curl_easy *rbce, *newrbce;

  Data_Get_Struct(self, ruby_curl_easy, rbce);

  newrbce = ALLOC(ruby_curl_easy);
  memcpy(newrbce, rbce, sizeof(ruby_curl_easy));
  newrbce->curl = curl_easy_duphandle(rbce->curl);
  newrbce->curl_headers = NULL;

  return Data_Wrap_Struct(cCurlEasy, curl_easy_mark, curl_easy_free, newrbce);
}

#connect_time ⇒ Float

Retrieve the time, in seconds, it took from the start until the connect to the remote host (or proxy) was completed.

Returns:

  • (Float) 


2148
2149
2150
2151
2152
2153
2154
2155
2156
 
# File 'ext/curb_easy.c', line 2148

static VALUE ruby_curl_easy_connect_time_get(VALUE self) {
  ruby_curl_easy *rbce;
  double time;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_CONNECT_TIME, &time);

  return rb_float_new(time);
}

#connect_timeout ⇒ Fixnum?

Obtain the maximum time in seconds that you allow the connection to the server to take.

Returns:

  • (Fixnum, nil) 


994
995
996
 
# File 'ext/curb_easy.c', line 994

static VALUE ruby_curl_easy_connect_timeout_get(VALUE self, VALUE connect_timeout) {
  CURB_IMMED_GETTER(ruby_curl_easy, connect_timeout, 0);
}

#connect_timeout=(fixnum) ⇒ Fixnum?

Set the maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once it has connected, this option is of no more use.

Set to nil (or zero) to disable connection timeout (it will then only timeout on the system’s internal timeouts).

Returns:

  • (Fixnum, nil) 


983
984
985
 
# File 'ext/curb_easy.c', line 983

static VALUE ruby_curl_easy_connect_timeout_set(VALUE self, VALUE connect_timeout) {
  CURB_IMMED_SETTER(ruby_curl_easy, connect_timeout, 0);
}

#content_type ⇒ nil

Retrieve the content-type of the downloaded object. This is the value read from the Content-Type: field. If you get nil, it means that the server didn’t send a valid Content-Type header or that the protocol used doesn’t support this.

Returns:

  • (nil) 


2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
 
# File 'ext/curb_easy.c', line 2412

static VALUE ruby_curl_easy_content_type_get(VALUE self) {
  ruby_curl_easy *rbce;
  char* type;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_CONTENT_TYPE, &type);

  if (type && type[0]) {    // curl returns empty string if none
    return rb_str_new2(type);
  } else {
    return Qnil;
  }
}

#cookiefile ⇒ Object

Obtain the cookiefile file for this Curl::Easy instance.



510
511
512
 
# File 'ext/curb_easy.c', line 510

static VALUE ruby_curl_easy_cookiefile_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, cookiefile);
}

#cookiefile=(cookiefile) ⇒ Object

Set a file that contains cookies to be sent in subsequent requests by this Curl::Easy instance.

Note that you must set enable_cookies true to enable the cookie engine, or this option will be ignored.



500
501
502
 
# File 'ext/curb_easy.c', line 500

static VALUE ruby_curl_easy_cookiefile_set(VALUE self, VALUE cookiefile) {
  CURB_OBJECT_SETTER(ruby_curl_easy, cookiefile);
}

#cookiejar ⇒ Object

Obtain the cookiejar file to use for this Curl::Easy instance.



534
535
536
 
# File 'ext/curb_easy.c', line 534

static VALUE ruby_curl_easy_cookiejar_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, cookiejar);
}

#cookiejar=(cookiejar) ⇒ Object

Set a cookiejar file to use for this Curl::Easy instance. Cookies from the response will be written into this file.

Note that you must set enable_cookies true to enable the cookie engine, or this option will be ignored.



524
525
526
 
# File 'ext/curb_easy.c', line 524

static VALUE ruby_curl_easy_cookiejar_set(VALUE self, VALUE cookiejar) {
  CURB_OBJECT_SETTER(ruby_curl_easy, cookiejar);
}

#cookies ⇒ Object

Obtain the cookies for this Curl::Easy instance.



487
488
489
 
# File 'ext/curb_easy.c', line 487

static VALUE ruby_curl_easy_cookies_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, cookies);
}

#cookies=(cookies) ⇒ Object

Set cookies to be sent by this Curl::Easy instance. The format of the string should be NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie should contain. Set multiple cookies in one string like this: “name1=content1; name2=content2;” etc.



477
478
479
 
# File 'ext/curb_easy.c', line 477

static VALUE ruby_curl_easy_cookies_set(VALUE self, VALUE cookies) {
  CURB_OBJECT_SETTER(ruby_curl_easy, cookies);
}

#dns_cache_timeout ⇒ Fixnum?

Obtain the dns cache timeout in seconds.

Returns:

  • (Fixnum, nil) 


1017
1018
1019
 
# File 'ext/curb_easy.c', line 1017

static VALUE ruby_curl_easy_dns_cache_timeout_get(VALUE self, VALUE dns_cache_timeout) {
  CURB_IMMED_GETTER(ruby_curl_easy, dns_cache_timeout, -1);
}

#dns_cache_timeout=(fixnum) ⇒ Fixnum?

Set the dns cache timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero (0) to completely disable caching, or set to nil (or -1) to make the cached entries remain forever. By default, libcurl caches this info for 60 seconds.

Returns:

  • (Fixnum, nil) 


1007
1008
1009
 
# File 'ext/curb_easy.c', line 1007

static VALUE ruby_curl_easy_dns_cache_timeout_set(VALUE self, VALUE dns_cache_timeout) {
  CURB_IMMED_SETTER(ruby_curl_easy, dns_cache_timeout, -1);
}

#download_speed ⇒ Float

Retrieve the average download speed that curl measured for the preceeding complete download.

Returns:

  • (Float) 


2303
2304
2305
2306
2307
2308
2309
2310
2311
 
# File 'ext/curb_easy.c', line 2303

static VALUE ruby_curl_easy_download_speed_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_SPEED_DOWNLOAD, &bytes);

  return rb_float_new(bytes);
}

#downloaded_bytes ⇒ Float

Retrieve the total amount of bytes that were downloaded in the preceeding transfer.

Returns:

  • (Float) 


2269
2270
2271
2272
2273
2274
2275
2276
2277
 
# File 'ext/curb_easy.c', line 2269

static VALUE ruby_curl_easy_downloaded_bytes_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_SIZE_DOWNLOAD, &bytes);

  return rb_float_new(bytes);
}

#downloaded_content_length ⇒ Float

Retrieve the content-length of the download. This is the value read from the Content-Length: field.

Returns:

  • (Float) 


2377
2378
2379
2380
2381
2382
2383
2384
2385
 
# File 'ext/curb_easy.c', line 2377

static VALUE ruby_curl_easy_downloaded_content_length_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD, &bytes);

  return rb_float_new(bytes);
}

#enable_cookies=(boolean) ⇒ Boolean

Configure whether the libcurl cookie engine is enabled for this Curl::Easy instance.

Returns:

  • (Boolean) 


1297
1298
1299
1300
 
# File 'ext/curb_easy.c', line 1297

static VALUE ruby_curl_easy_enable_cookies_set(VALUE self, VALUE enable_cookies)
{
  CURB_BOOLEAN_SETTER(ruby_curl_easy, enable_cookies);
}

#enable_cookies? ⇒ Boolean

Determine whether the libcurl cookie engine is enabled for this Curl::Easy instance.

Returns:

  • (Boolean) 


1309
1310
1311
 
# File 'ext/curb_easy.c', line 1309

static VALUE ruby_curl_easy_enable_cookies_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, enable_cookies);
}

#encoding ⇒ Object

Get the set encoding types



631
632
633
 
# File 'ext/curb_easy.c', line 631

static VALUE ruby_curl_easy_encoding_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, encoding);
}

#encoding= ⇒ Object

Set the accepted encoding types, curl will handle all of the decompression



621
622
623
 
# File 'ext/curb_easy.c', line 621

static VALUE ruby_curl_easy_encoding_set(VALUE self, VALUE encoding) {
  CURB_OBJECT_SETTER(ruby_curl_easy, encoding);
}

#escape("some text") ⇒ Object

Convert the given input string to a URL encoded string and return the result. All input characters that are not a-z, A-Z or 0-9 are converted to their “URL escaped” version (%NN where NN is a two-digit hexadecimal number).



2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
 
# File 'ext/curb_easy.c', line 2570

static VALUE ruby_curl_easy_escape(VALUE self, VALUE str) {
  ruby_curl_easy *rbce;
  char *result;
  VALUE rresult;

  Data_Get_Struct(self, ruby_curl_easy, rbce);

#if (LIBCURL_VERSION_NUM >= 0x070f04)
  result = (char*)curl_easy_escape(rbce->curl, StringValuePtr(str), RSTRING_LEN(str));
#else
  result = (char*)curl_escape(StringValuePtr(str), RSTRING_LEN(str));
#endif

  rresult = rb_str_new2(result);
  curl_free(result);

  return rresult;
}

#fetch_file_time=(boolean) ⇒ Boolean

Configure whether this Curl instance will fetch remote file times, if available.

Returns:

  • (Boolean) 


1077
1078
1079
 
# File 'ext/curb_easy.c', line 1077

static VALUE ruby_curl_easy_fetch_file_time_set(VALUE self, VALUE fetch_file_time) {
  CURB_BOOLEAN_SETTER(ruby_curl_easy, fetch_file_time);
}

#fetch_file_time? ⇒ Boolean

Determine whether this Curl instance will fetch remote file times, if available.

Returns:

  • (Boolean) 


1088
1089
1090
 
# File 'ext/curb_easy.c', line 1088

static VALUE ruby_curl_easy_fetch_file_time_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, fetch_file_time);
}

#file_time ⇒ Fixnum

Retrieve the remote time of the retrieved document (in number of seconds since 1 jan 1970 in the GMT/UTC time zone). If you get -1, it can be because of many reasons (unknown, the server hides it or the server doesn’t support the command that tells document time etc) and the time of the document is unknown.

Note that you must tell the server to collect this information before the transfer is made, by setting fetch_file_time? to true, or you will unconditionally get a -1 back.

This requires libcurl 7.5 or higher - otherwise -1 is unconditionally returned.

Returns:

  • (Fixnum) 


2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
 
# File 'ext/curb_easy.c', line 2092

static VALUE ruby_curl_easy_file_time_get(VALUE self) {
#ifdef HAVE_CURLINFO_FILETIME
  ruby_curl_easy *rbce;
  long time;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_FILETIME, &time);

  return LONG2NUM(time);
#else
  rb_warn("Installed libcurl is too old to support file_time");
  return INT2FIX(0);
#endif
}

#follow_location=(boolean) ⇒ Boolean

Configure whether this Curl instance will follow Location: headers in HTTP responses. Redirects will only be followed to the extent specified by max_redirects.

Returns:

  • (Boolean) 


1202
1203
1204
 
# File 'ext/curb_easy.c', line 1202

static VALUE ruby_curl_easy_follow_location_set(VALUE self, VALUE follow_location) {
  CURB_BOOLEAN_SETTER(ruby_curl_easy, follow_location);
}

#follow_location? ⇒ Boolean

Determine whether this Curl instance will follow Location: headers in HTTP responses.

Returns:

  • (Boolean) 


1213
1214
1215
 
# File 'ext/curb_easy.c', line 1213

static VALUE ruby_curl_easy_follow_location_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, follow_location);
}

#content_type ⇒ nil

Retrieve the path of the entry path. That is the initial path libcurl ended up in when logging on to the remote FTP server. This returns nil if something is wrong.

(requires libcurl 7.15.4 or higher, otherwise nil is always returned).

Returns:

  • (nil) 


2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
 
# File 'ext/curb_easy.c', line 2524

static VALUE ruby_curl_easy_ftp_entry_path_get(VALUE self) {
#ifdef HAVE_CURLINFO_FTP_ENTRY_PATH
  ruby_curl_easy *rbce;
  char* path = NULL;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_FTP_ENTRY_PATH, &path);

  if (path && path[0]) {    // curl returns NULL or empty string if none
    return rb_str_new2(path);
  } else {
    return Qnil;
  }
#else
  rb_warn("Installed libcurl is too old to support num_connects");
  return Qnil;
#endif
}

#ftp_response_timeout ⇒ Fixnum?

Obtain the maximum time that libcurl will wait for FTP command responses.

Returns:

  • (Fixnum, nil) 


1044
1045
1046
 
# File 'ext/curb_easy.c', line 1044

static VALUE ruby_curl_easy_ftp_response_timeout_get(VALUE self, VALUE ftp_response_timeout) {
  CURB_IMMED_GETTER(ruby_curl_easy, ftp_response_timeout, 0);
}

#ftp_response_timeout=(fixnum) ⇒ Fixnum?

Set a timeout period (in seconds) on the amount of time that the server is allowed to take in order to generate a response message for a command before the session is considered hung. While curl is waiting for a response, this value overrides timeout. It is recommended that if used in conjunction with timeout, you set ftp_response_timeout to a value smaller than timeout.

Ignored if libcurl version is < 7.10.8.

Returns:

  • (Fixnum, nil) 


1034
1035
1036
 
# File 'ext/curb_easy.c', line 1034

static VALUE ruby_curl_easy_ftp_response_timeout_set(VALUE self, VALUE ftp_response_timeout) {
  CURB_IMMED_SETTER(ruby_curl_easy, ftp_response_timeout, 0);
}

#easy=(Curl) ⇒ Object #head=(true) ⇒ Object #end ⇒ Object #perform ⇒ Object 



1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
 
# File 'ext/curb_easy.c', line 1947

static VALUE ruby_curl_easy_set_head_option(VALUE self, VALUE onoff) {
  ruby_curl_easy *rbce;

  Data_Get_Struct(self, ruby_curl_easy, rbce);

  if( onoff == Qtrue ) {
    curl_easy_setopt(rbce->curl, CURLOPT_NOBODY, 1);
  }
  else {
    curl_easy_setopt(rbce->curl, CURLOPT_NOBODY, 0);
  }

  return onoff;
}

#header_in_body=(boolean) ⇒ Boolean

Configure whether this Curl instance will return HTTP headers combined with body data. If this option is set true, both header and body data will go to body_str (or the configured on_body handler).

Returns:

  • (Boolean) 


1157
1158
1159
 
# File 'ext/curb_easy.c', line 1157

static VALUE ruby_curl_easy_header_in_body_set(VALUE self, VALUE header_in_body) {
  CURB_BOOLEAN_SETTER(ruby_curl_easy, header_in_body);
}

#header_in_body? ⇒ Boolean

Determine whether this Curl instance will verify the SSL peer certificate.

Returns:

  • (Boolean) 


1168
1169
1170
 
# File 'ext/curb_easy.c', line 1168

static VALUE ruby_curl_easy_header_in_body_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, header_in_body);
}

#header_size ⇒ Fixnum

Retrieve the total size of all the headers received in the preceeding transfer.

Returns:

  • (Fixnum) 


2320
2321
2322
2323
2324
2325
2326
2327
2328
 
# File 'ext/curb_easy.c', line 2320

static VALUE ruby_curl_easy_header_size_get(VALUE self) {
  ruby_curl_easy *rbce;
  long size;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_HEADER_SIZE, &size);

  return LONG2NUM(size);
}

#header_str ⇒ Object

Return the response header from the previous call to perform. This is populated by the default on_header handler - if you supply your own header handler, this string will be empty.



2006
2007
2008
 
# File 'ext/curb_easy.c', line 2006

static VALUE ruby_curl_easy_header_str_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, header_data);
}

#headers ⇒ Hash, ...

Obtain the custom HTTP headers for following requests.

Returns:

  • (Hash, Array, Str) 


396
397
398
 
# File 'ext/curb_easy.c', line 396

static VALUE ruby_curl_easy_headers_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, headers);
}

#headers=(headers) ⇒ Object

easy.headers = => “val” …, “Header” => “val” => [“Header: val”, …]

easy.headers = ["Header: val" ..., "Header: val"]         => ["Header: val", ...]

Set custom HTTP headers for following requests. This can be used to add custom headers, or override standard headers used by libcurl. It defaults to a Hash.

For example to set a standard or custom header:

easy.headers["MyHeader"] = "myval"

To remove a standard header (this is useful when removing libcurls default ‘Expect: 100-Continue’ header when using HTTP form posts):

easy.headers["Expect:"] = ''

Anything passed to libcurl as a header will be converted to a string during the perform step.



386
387
388
 
# File 'ext/curb_easy.c', line 386

static VALUE ruby_curl_easy_headers_set(VALUE self, VALUE headers) {
  CURB_OBJECT_SETTER(ruby_curl_easy, headers);
}

#http_auth_types ⇒ Fixnum?

Obtain the HTTP authentication types that may be used for the following perform calls.

Returns:

  • (Fixnum, nil) 


892
893
894
 
# File 'ext/curb_easy.c', line 892

static VALUE ruby_curl_easy_http_auth_types_get(VALUE self) {
  CURB_IMMED_GETTER(ruby_curl_easy, http_auth_types, 0);
}

#http_auth_types=(fixnum) ⇒ Fixnum?

Set the HTTP authentication types that may be used for the following perform calls. This is a bitmap made by ORing together the Curl::CURLAUTH constants.

Returns:

  • (Fixnum, nil) 


881
882
883
 
# File 'ext/curb_easy.c', line 881

static VALUE ruby_curl_easy_http_auth_types_set(VALUE self, VALUE http_auth_types) {
  CURB_IMMED_SETTER(ruby_curl_easy, http_auth_types, 0);
}

#http_connect_code ⇒ Fixnum

Retrieve the last received proxy response code to a CONNECT request.

Returns:

  • (Fixnum) 


2065
2066
2067
2068
2069
2070
2071
2072
2073
 
# File 'ext/curb_easy.c', line 2065

static VALUE ruby_curl_easy_http_connect_code_get(VALUE self) {
  ruby_curl_easy *rbce;
  long code;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_HTTP_CONNECTCODE, &code);

  return LONG2NUM(code);
}

#http_delete ⇒ Object

DELETE the currently configured URL using the current options set for this Curl::Easy instance. This method always returns true, or raises an exception (defined under Curl::Err) on error.



1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
 
# File 'ext/curb_easy.c', line 1813

static VALUE ruby_curl_easy_perform_delete(VALUE self) {
  ruby_curl_easy *rbce;
  CURL *curl;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl = rbce->curl;

  curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE");

  VALUE retval = handle_perform(self,rbce);

  curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, NULL);

  return retval;
}

#http_get ⇒ true

GET the currently configured URL using the current options set for this Curl::Easy instance. This method always returns true, or raises an exception (defined under Curl::Err) on error.

Returns:

  • (true) 


1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
 
# File 'ext/curb_easy.c', line 1793

static VALUE ruby_curl_easy_perform_get(VALUE self) {
  ruby_curl_easy *rbce;
  CURL *curl;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl = rbce->curl;

  curl_easy_setopt(curl, CURLOPT_HTTPGET, 1);

  return handle_perform(self,rbce);
}

#http_head ⇒ true

Request headers from the currently configured URL using the HEAD method and current options set for this Curl::Easy instance. This method always returns true, or raises an exception (defined under Curl::Err) on error.

Returns:

  • (true) 


1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
 
# File 'ext/curb_easy.c', line 1925

static VALUE ruby_curl_easy_perform_head(VALUE self) {
  ruby_curl_easy *rbce;
  CURL *curl;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl = rbce->curl;

  curl_easy_setopt(curl, CURLOPT_NOBODY, 1);

  VALUE ret = handle_perform(self,rbce);

  curl_easy_setopt(curl, CURLOPT_NOBODY, 0);
  return ret;
}

#http_post("url = encoded%20form%20data;and=so%20on") ⇒ true #http_post("url = encoded%20form%20data", "and = so%20on", ...) ⇒ true #http_post("url = encoded%20form%20data", Curl: :PostField, "and = so%20on", ...) ⇒ true #http_post(Curl: :PostField, Curl: :PostField..., Curl: :PostField) ⇒ true

POST the specified formdata to the currently configured URL using the current options set for this Curl::Easy instance. This method always returns true, or raises an exception (defined under Curl::Err) on error.

The Content-type of the POST is determined by the current setting of multipart_form_post? , according to the following rules:

  • When false (the default): the form will be POSTed with a content-type of ‘application/x-www-form-urlencoded’, and any of the four calling forms may be used.

  • When true: the form will be POSTed with a content-type of ‘multipart/formdata’. Only the last calling form may be used, i.e. only PostField instances may be POSTed. In this mode, individual fields’ content-types are recognised, and file upload fields are supported.

Overloads:

  • #http_post("url = encoded%20form%20data;and=so%20on") ⇒ true

    Returns:

    • (true)
  • #http_post("url = encoded%20form%20data", "and = so%20on", ...) ⇒ true

    Returns:

    • (true)
  • #http_post("url = encoded%20form%20data", Curl: :PostField, "and = so%20on", ...) ⇒ true

    Returns:

    • (true)
  • #http_post(Curl: :PostField, Curl: :PostField..., Curl: :PostField) ⇒ true

    Returns:

    • (true) 


1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
 
# File 'ext/curb_easy.c', line 1869

static VALUE ruby_curl_easy_perform_post(int argc, VALUE *argv, VALUE self) {
  ruby_curl_easy *rbce;
  CURL *curl;
  int i;
  VALUE args_ary;

  rb_scan_args(argc, argv, "*", &args_ary);

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl = curl_easy_duphandle(rbce->curl);
  curl_easy_cleanup(rbce->curl);
  rbce->curl = curl;

  if (rbce->multipart_form_post) {
    VALUE ret;
    struct curl_httppost *first = NULL, *last = NULL;

    // Make the multipart form
    for (i = 0; i < argc; i++) {
      if (rb_obj_is_instance_of(argv[i], cCurlPostField)) {
        append_to_form(argv[i], &first, &last);
      } else {
        rb_raise(eCurlErrInvalidPostField, "You must use PostFields only with multipart form posts");
        return Qnil;
      }
    }

    curl_easy_setopt(curl, CURLOPT_POST, 0);
    curl_easy_setopt(curl, CURLOPT_HTTPPOST, first);
    ret = handle_perform(self,rbce);
    curl_formfree(first);

    return ret;
  } else {
    VALUE post_body;
    if ((post_body = rb_funcall(args_ary, idJoin, 1, rbstrAmp)) == Qnil) {
      rb_raise(eCurlErrError, "Failed to join arguments");
      return Qnil;
    } else {
      ruby_curl_easy_post_body_set(self, post_body);

      return handle_perform(self,rbce);
    }
  }
}

#http_put(data) ⇒ true

PUT the supplied data to the currently configured URL using the current options set for this Curl::Easy instance. This method always returns true, or raises an exception (defined under Curl::Err) on error.

Returns:

  • (true) 


1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
 
# File 'ext/curb_easy.c', line 1970

static VALUE ruby_curl_easy_perform_put(VALUE self, VALUE data) {
  ruby_curl_easy *rbce;
  CURL *curl;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl = rbce->curl;
  
  ruby_curl_easy_put_data_set(self, data);
  
  VALUE ret = handle_perform(self, rbce);
  
  return ret;
}

#inspect ⇒ "#<Curl::Easy http://google.com/>"

Returns:



2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
 
# File 'ext/curb_easy.c', line 2547

static VALUE ruby_curl_easy_inspect(VALUE self) {
  char buf[64];
  ruby_curl_easy *rbce;
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  // "#<Net::HTTP http://www.google.com/:80 open=false>"
  snprintf(buf,sizeof(buf),"#<Curl::Easy %s", RSTRING_PTR(rbce->url));
  size_t r = strlen(buf);
  buf[r-1] = '>';
  return rb_str_new(buf,r);
}

#interface ⇒ Object

Obtain the interface name that is used as the outgoing network interface. The name can be an interface name, an IP address or a host name.



418
419
420
 
# File 'ext/curb_easy.c', line 418

static VALUE ruby_curl_easy_interface_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, interface);
}

#interface=(interface) ⇒ Object

Set the interface name to use as the outgoing network interface. The name can be an interface name, an IP address or a host name.



407
408
409
 
# File 'ext/curb_easy.c', line 407

static VALUE ruby_curl_easy_interface_set(VALUE self, VALUE interface) {
  CURB_OBJECT_SETTER(ruby_curl_easy, interface);
}

#last_effective_url ⇒ nil

Retrieve the last effective URL used by this instance. This is the URL used in the last perform call, and may differ from the value of easy.url.

Returns:

  • (nil) 


2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
 
# File 'ext/curb_easy.c', line 2021

static VALUE ruby_curl_easy_last_effective_url_get(VALUE self) {
  ruby_curl_easy *rbce;
  char* url;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_EFFECTIVE_URL, &url);

  if (url && url[0]) {    // curl returns empty string if none
    return rb_str_new2(url);
  } else {
    return Qnil;
  }
}

#local_port ⇒ Fixnum?

Obtain the local port that will be used for the following perform calls.

This option is ignored if compiled against libcurl < 7.15.2.

Returns:

  • (Fixnum, nil) 


797
798
799
 
# File 'ext/curb_easy.c', line 797

static VALUE ruby_curl_easy_local_port_get(VALUE self) {
  CURB_IMMED_PORT_GETTER(ruby_curl_easy, local_port);
}

#local_port=(fixnum) ⇒ Fixnum?

Set the local port that will be used for the following perform calls.

Passing nil will return to the default behaviour (no local port preference).

This option is ignored if compiled against libcurl < 7.15.2.

Returns:

  • (Fixnum, nil) 


785
786
787
 
# File 'ext/curb_easy.c', line 785

static VALUE ruby_curl_easy_local_port_set(VALUE self, VALUE local_port) {
  CURB_IMMED_PORT_SETTER(ruby_curl_easy, local_port, "port");
}

#local_port_range ⇒ Fixnum?

Obtain the local port range that will be used for the following perform calls.

This option is ignored if compiled against libcurl < 7.15.2.

Returns:

  • (Fixnum, nil) 


828
829
830
 
# File 'ext/curb_easy.c', line 828

static VALUE ruby_curl_easy_local_port_range_get(VALUE self) {
  CURB_IMMED_PORT_GETTER(ruby_curl_easy, local_port_range);
}

#local_port_range=(fixnum) ⇒ Fixnum?

Set the local port range that will be used for the following perform calls. This is a number (between 0 and 65535) that determines how far libcurl may deviate from the supplied local_port in order to find an available port.

If you set local_port it’s also recommended that you set this, since it is fairly likely that your specified port will be unavailable.

This option is ignored if compiled against libcurl < 7.15.2.

Returns:

  • (Fixnum, nil) 


815
816
817
 
# File 'ext/curb_easy.c', line 815

static VALUE ruby_curl_easy_local_port_range_set(VALUE self, VALUE local_port_range) {
  CURB_IMMED_PORT_SETTER(ruby_curl_easy, local_port_range, "port range");
}

#max_redirects ⇒ Fixnum?

Obtain the maximum number of redirections to follow in the following perform calls.

Returns:

  • (Fixnum, nil) 


941
942
943
 
# File 'ext/curb_easy.c', line 941

static VALUE ruby_curl_easy_max_redirects_get(VALUE self) {
  CURB_IMMED_GETTER(ruby_curl_easy, max_redirs, -1);
}

#max_redirects=(fixnum) ⇒ Fixnum?

Set the maximum number of redirections to follow in the following perform calls. Set to nil or -1 allow an infinite number (the default). Setting this option only makes sense if follow_location is also set true.

With libcurl >= 7.15.1, setting this to 0 will cause libcurl to refuse any redirect.

Returns:

  • (Fixnum, nil) 


930
931
932
 
# File 'ext/curb_easy.c', line 930

static VALUE ruby_curl_easy_max_redirects_set(VALUE self, VALUE max_redirs) {
  CURB_IMMED_SETTER(ruby_curl_easy, max_redirs, -1);
}

#multipart_form_post=(boolean) ⇒ Boolean

Configure whether this Curl instance uses multipart/formdata content type for HTTP POST requests. If this is false (the default), then the application/x-www-form-urlencoded content type is used for the form data.

If this is set true, you must pass one or more PostField instances to the http_post method - no support for posting multipart forms from a string is provided.

Returns:

  • (Boolean) 


1274
1275
1276
1277
 
# File 'ext/curb_easy.c', line 1274

static VALUE ruby_curl_easy_multipart_form_post_set(VALUE self, VALUE multipart_form_post)
{
  CURB_BOOLEAN_SETTER(ruby_curl_easy, multipart_form_post);
}

#multipart_form_post? ⇒ Boolean

Determine whether this Curl instance uses multipart/formdata content type for HTTP POST requests.

Returns:

  • (Boolean) 


1286
1287
1288
 
# File 'ext/curb_easy.c', line 1286

static VALUE ruby_curl_easy_multipart_form_post_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, multipart_form_post);
}

#name_lookup_time ⇒ Float

Retrieve the time, in seconds, it took from the start until the name resolving was completed.

Returns:

  • (Float) 


2131
2132
2133
2134
2135
2136
2137
2138
2139
 
# File 'ext/curb_easy.c', line 2131

static VALUE ruby_curl_easy_name_lookup_time_get(VALUE self) {
  ruby_curl_easy *rbce;
  double time;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_NAMELOOKUP_TIME, &time);

  return rb_float_new(time);
}

#native_cert= ⇒ Object

Allow the incoming cert string to be file:password but be careful to not use a colon from a windows file path as the split point. Mimic what curl’s main does



45
 
# File 'lib/curb.rb', line 45

alias_method :native_cert=, :cert=

#num_connects ⇒ Integer

Retrieve the number of new connections libcurl had to create to achieve the previous transfer (only the successful connects are counted). Combined with redirect_count you are able to know how many times libcurl successfully reused existing connection(s) or not.

See the Connection Options of curl_easy_setopt(3) to see how libcurl tries to make persistent connections to save time.

(requires libcurl 7.12.3 or higher, otherwise -1 is always returned).

Returns:

  • (Integer) 


2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
 
# File 'ext/curb_easy.c', line 2483

static VALUE ruby_curl_easy_num_connects_get(VALUE self) {
#ifdef HAVE_CURLINFO_NUM_CONNECTS
  ruby_curl_easy *rbce;
  long result;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_NUM_CONNECTS, &result);

  return LONG2NUM(result);
#else
  rb_warn("Installed libcurl is too old to support num_connects");
  return INT2FIX(-1);
#endif
}

#on_body {|body_data| ... } ⇒ Object

Assign or remove the on_body handler for this Curl::Easy instance. To remove a previously-supplied handler, call this method with no attached block.

The on_body handler is called for each chunk of response body passed back by libcurl during perform. It should perform any processing necessary, and return the actual number of bytes handled. Normally, this will equal the length of the data string, and CURL will continue processing. If the returned length does not equal the input length, CURL will abort the processing with a Curl::Err::AbortedByCallbackError.

Yields:

  • (body_data) 


1330
1331
1332
 
# File 'ext/curb_easy.c', line 1330

static VALUE ruby_curl_easy_on_body_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_SETTER(ruby_curl_easy, body_proc);
}

#on_complete { ... } ⇒ Object

Assign or remove the on_complete handler for this Curl::Easy instance. To remove a previously-supplied handler, call this method with no attached block.

The on_complete handler is called when the request is finished.

Yields:



1374
1375
1376
 
# File 'ext/curb_easy.c', line 1374

static VALUE ruby_curl_easy_on_complete_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_SETTER(ruby_curl_easy, complete_proc);
}

#on_debug {|type, data| ... } ⇒ Object

Assign or remove the on_debug handler for this Curl::Easy instance. To remove a previously-supplied handler, call this method with no attached block.

The on_debug handler, if configured, will receive detailed information from libcurl during the perform call. This can be useful for debugging. Setting a debug handler overrides libcurl’s internal handler, disabling any output from verbose, if set.

The type argument will match one of the Curl::Easy::CURLINFO_XXXX constants, and specifies the kind of information contained in the data. The data is passed as a String.

Yields:

  • (type, data) 


1432
1433
1434
 
# File 'ext/curb_easy.c', line 1432

static VALUE ruby_curl_easy_on_debug_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_SETTER(ruby_curl_easy, debug_proc);
}

#on_failure { ... } ⇒ Object

Assign or remove the on_failure handler for this Curl::Easy instance. To remove a previously-supplied handler, call this method with no attached block.

The on_failure handler is called when the request is finished with a status of 50x

Yields:



1360
1361
1362
 
# File 'ext/curb_easy.c', line 1360

static VALUE ruby_curl_easy_on_failure_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_SETTER(ruby_curl_easy, failure_proc);
}

#on_header {|header_data| ... } ⇒ Object

Assign or remove the on_header handler for this Curl::Easy instance. To remove a previously-supplied handler, call this method with no attached block.

The on_header handler is called for each chunk of response header passed back by libcurl during perform. The semantics are the same as for the block supplied to on_body.

Yields:

  • (header_data) 


1390
1391
1392
 
# File 'ext/curb_easy.c', line 1390

static VALUE ruby_curl_easy_on_header_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_SETTER(ruby_curl_easy, header_proc);
}

#on_progress {|dl_total, dl_now, ul_total, ul_now| ... } ⇒ Object

Assign or remove the on_progress handler for this Curl::Easy instance. To remove a previously-supplied handler, call this method with no attached block.

The on_progress handler is called regularly by libcurl (approximately once per second) during transfers to allow the application to receive progress information. There is no guarantee that the reported progress will change between calls.

The result of the block call determines whether libcurl continues the transfer. Returning a non-true value (i.e. nil or false) will cause the transfer to abort, throwing a Curl::Err::AbortedByCallbackError.

Yields:

  • (dl_total, dl_now, ul_total, ul_now) 


1411
1412
1413
 
# File 'ext/curb_easy.c', line 1411

static VALUE ruby_curl_easy_on_progress_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_SETTER(ruby_curl_easy, progress_proc);
}

#on_success { ... } ⇒ Object

Assign or remove the on_success handler for this Curl::Easy instance. To remove a previously-supplied handler, call this method with no attached block.

The on_success handler is called when the request is finished with a status of 20x

Yields:



1345
1346
1347
 
# File 'ext/curb_easy.c', line 1345

static VALUE ruby_curl_easy_on_success_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_SETTER(ruby_curl_easy, success_proc);
}

#os_errno ⇒ Integer

Retrieve the errno variable from a connect failure (requires libcurl 7.12.2 or higher, otherwise 0 is always returned).

Returns:

  • (Integer) 


2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
 
# File 'ext/curb_easy.c', line 2454

static VALUE ruby_curl_easy_os_errno_get(VALUE self) {
#ifdef HAVE_CURLINFO_OS_ERRNO
  ruby_curl_easy *rbce;
  long result;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_OS_ERRNO, &result);

  return LONG2NUM(result);
#else
  rb_warn("Installed libcurl is too old to support os_errno");
  return INT2FIX(0);
#endif
}

#perform ⇒ true

Transfer the currently configured URL using the options set for this Curl::Easy instance. If this is an HTTP URL, it will be transferred via the GET or HEAD request method.

Returns:

  • (true) 


1837
1838
1839
1840
1841
1842
1843
 
# File 'ext/curb_easy.c', line 1837

static VALUE ruby_curl_easy_perform(VALUE self) {
  ruby_curl_easy *rbce;

  Data_Get_Struct(self, ruby_curl_easy, rbce);

  return handle_perform(self,rbce);
}

#post_body ⇒ nil

Obtain the POST body used in this Curl::Easy instance.

Returns:

  • (nil) 


704
705
706
 
# File 'ext/curb_easy.c', line 704

static VALUE ruby_curl_easy_post_body_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, postdata_buffer);
}

#post_body=(post_body) ⇒ Object

Sets the POST body of this Curl::Easy instance. This is expected to be URL encoded; no additional processing or encoding is done on the string. The content-type header will be set to application/x-www-form-urlencoded.

This is handy if you want to perform a POST against a Curl::Multi instance.



666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
 
# File 'ext/curb_easy.c', line 666

static VALUE ruby_curl_easy_post_body_set(VALUE self, VALUE post_body) {
  ruby_curl_easy *rbce;
  CURL *curl;
  
  char *data;
  long len;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  
  curl = rbce->curl;
  
  if ( post_body == Qnil ) {
    rbce->postdata_buffer = Qnil;
    
  } else {  
    data = StringValuePtr(post_body);
    len = RSTRING_LEN(post_body);
  
    // Store the string, since it has to hang around for the duration of the 
    // request.  See CURLOPT_POSTFIELDS in the libcurl docs.
    rbce->postdata_buffer = post_body;
  
    curl_easy_setopt(curl, CURLOPT_POST, 1);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
    curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, len);
    
    return post_body;
  }
  
  return Qnil;
}

#pre_transfer_time ⇒ Float

Retrieve the time, in seconds, it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved.

Returns:

  • (Float) 


2167
2168
2169
2170
2171
2172
2173
2174
2175
 
# File 'ext/curb_easy.c', line 2167

static VALUE ruby_curl_easy_pre_transfer_time_get(VALUE self) {
  ruby_curl_easy *rbce;
  double time;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_PRETRANSFER_TIME, &time);

  return rb_float_new(time);
}

#proxy_auth_types ⇒ Fixnum?

Obtain the proxy authentication types that may be used for the following perform calls.

Returns:

  • (Fixnum, nil) 


915
916
917
 
# File 'ext/curb_easy.c', line 915

static VALUE ruby_curl_easy_proxy_auth_types_get(VALUE self) {
  CURB_IMMED_GETTER(ruby_curl_easy, proxy_auth_types, 0);
}

#proxy_auth_types=(fixnum) ⇒ Fixnum?

Set the proxy authentication types that may be used for the following perform calls. This is a bitmap made by ORing together the Curl::CURLAUTH constants.

Returns:

  • (Fixnum, nil) 


904
905
906
 
# File 'ext/curb_easy.c', line 904

static VALUE ruby_curl_easy_proxy_auth_types_set(VALUE self, VALUE proxy_auth_types) {
  CURB_IMMED_SETTER(ruby_curl_easy, proxy_auth_types, 0);
}

#proxy_port ⇒ Fixnum?

Obtain the proxy port that will be used for the following perform calls.

Returns:

  • (Fixnum, nil) 


848
849
850
 
# File 'ext/curb_easy.c', line 848

static VALUE ruby_curl_easy_proxy_port_get(VALUE self) {
  CURB_IMMED_PORT_GETTER(ruby_curl_easy, proxy_port);
}

#proxy_port=(fixnum) ⇒ Fixnum?

Set the proxy port that will be used for the following perform calls.

Returns:

  • (Fixnum, nil) 


838
839
840
 
# File 'ext/curb_easy.c', line 838

static VALUE ruby_curl_easy_proxy_port_set(VALUE self, VALUE proxy_port) {
  CURB_IMMED_PORT_SETTER(ruby_curl_easy, proxy_port, "port");
}

#proxy_tunnel=(boolean) ⇒ Boolean

Configure whether this Curl instance will use proxy tunneling.

Returns:

  • (Boolean) 


1056
1057
1058
 
# File 'ext/curb_easy.c', line 1056

static VALUE ruby_curl_easy_proxy_tunnel_set(VALUE self, VALUE proxy_tunnel) {
  CURB_BOOLEAN_SETTER(ruby_curl_easy, proxy_tunnel);
}

#proxy_tunnel? ⇒ Boolean

Determine whether this Curl instance will use proxy tunneling.

Returns:

  • (Boolean) 


1066
1067
1068
 
# File 'ext/curb_easy.c', line 1066

static VALUE ruby_curl_easy_proxy_tunnel_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, proxy_tunnel);
}

#proxy_type ⇒ Fixnum?

Obtain the proxy type that will be used for the following perform calls.

Returns:

  • (Fixnum, nil) 


869
870
871
 
# File 'ext/curb_easy.c', line 869

static VALUE ruby_curl_easy_proxy_type_get(VALUE self) {
  CURB_IMMED_GETTER(ruby_curl_easy, proxy_type, -1);
}

#proxy_type=(fixnum) ⇒ Fixnum?

Set the proxy type that will be used for the following perform calls. This should be one of the Curl::CURLPROXY constants.

Returns:

  • (Fixnum, nil) 


859
860
861
 
# File 'ext/curb_easy.c', line 859

static VALUE ruby_curl_easy_proxy_type_set(VALUE self, VALUE proxy_type) {
  CURB_IMMED_SETTER(ruby_curl_easy, proxy_type, -1);
}

#proxy_url ⇒ Object

Obtain the HTTP Proxy URL that will be used by subsequent calls to perform.



360
361
362
 
# File 'ext/curb_easy.c', line 360

static VALUE ruby_curl_easy_proxy_url_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, proxy_url);
}

#proxy_url=(proxy_url) ⇒ Object

Set the URL of the HTTP proxy to use for subsequent calls to perform. The URL should specify the the host name or dotted IP address. To specify port number in this string, append :[port] to the end of the host name. The proxy string may be prefixed with [protocol]:// since any such prefix will be ignored. The proxy’s port number may optionally be specified with the separate option proxy_port .

When you tell the library to use an HTTP proxy, libcurl will transparently convert operations to HTTP even if you specify an FTP URL etc. This may have an impact on what other features of the library you can use, such as FTP specifics that don’t work unless you tunnel through the HTTP proxy. Such tunneling is activated with proxy_tunnel = true.

libcurl respects the environment variables http_proxy, ftp_proxy, all_proxy etc, if any of those is set. The proxy_url option does however override any possibly set environment variables.

Starting with libcurl 7.14.1, the proxy host string given in environment variables can be specified the exact same way as the proxy can be set with proxy_url, including protocol prefix (http://) and embedded user + password.



350
351
352
 
# File 'ext/curb_easy.c', line 350

static VALUE ruby_curl_easy_proxy_url_set(VALUE self, VALUE proxy_url) {
  CURB_OBJECT_SETTER(ruby_curl_easy, proxy_url);
}

#proxypwd ⇒ Object

Obtain the username/password string that will be used for proxy connection during subsequent calls to perform. The supplied string should have the form “username:password”



464
465
466
 
# File 'ext/curb_easy.c', line 464

static VALUE ruby_curl_easy_proxypwd_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, proxypwd);
}

#proxypwd=(proxypwd) ⇒ Object

Set the username/password string to use for proxy connection during subsequent calls to perform. The supplied string should have the form “username:password”



452
453
454
 
# File 'ext/curb_easy.c', line 452

static VALUE ruby_curl_easy_proxypwd_set(VALUE self, VALUE proxypwd) {
  CURB_OBJECT_SETTER(ruby_curl_easy, proxypwd);
}

#put_data=(data) ⇒ Object

Points this Curl::Easy instance to data to be uploaded via PUT. This sets the request to a PUT type request - useful if you want to PUT via a multi handle.



716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
 
# File 'ext/curb_easy.c', line 716

static VALUE ruby_curl_easy_put_data_set(VALUE self, VALUE data) {
  ruby_curl_easy *rbce;
  CURL *curl;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);

  VALUE upload = ruby_curl_upload_new(cCurlUpload);
  ruby_curl_upload_stream_set(upload,data);

  curl = rbce->curl;
  rbce->upload = upload; /* keep the upload object alive as long as
                            the easy handle is active or until the upload
                            is complete or terminated... */

  curl_easy_setopt(curl, CURLOPT_NOBODY,0);
  curl_easy_setopt(curl, CURLOPT_UPLOAD, 1);
  curl_easy_setopt(curl, CURLOPT_READFUNCTION, (curl_read_callback)read_data_handler);
  curl_easy_setopt(curl, CURLOPT_READDATA, rbce);

  /* 
   * we need to set specific headers for the PUT to work... so
   * convert the internal headers structure to a HASH if one is set
   */
  if (rbce->headers != Qnil) {
    if (rb_type(rbce->headers) == T_ARRAY || rb_type(rbce->headers) == T_STRING) {
      rb_raise(rb_eRuntimeError, "Must set headers as a HASH to modify the headers in an PUT request");
    }
  }

  if (rb_respond_to(data, rb_intern("read"))) {
    VALUE stat = rb_funcall(data, rb_intern("stat"), 0);
    if( stat ) {
      if( rb_hash_aref(rbce->headers, rb_str_new2("Expect")) == Qnil ) {
        rb_hash_aset(rbce->headers, rb_str_new2("Expect"), rb_str_new2(""));
      }
      VALUE size = rb_funcall(stat, rb_intern("size"), 0);
      curl_easy_setopt(curl, CURLOPT_INFILESIZE, FIX2INT(size));
    }
    else if( rb_hash_aref(rbce->headers, rb_str_new2("Transfer-Encoding")) == Qnil ) {
      rb_hash_aset(rbce->headers, rb_str_new2("Transfer-Encoding"), rb_str_new2("chunked"));
    }
  }
  else if (rb_respond_to(data, rb_intern("to_s"))) {
    curl_easy_setopt(curl, CURLOPT_INFILESIZE, RSTRING_LEN(data));
    if( rb_hash_aref(rbce->headers, rb_str_new2("Expect")) == Qnil ) {
      rb_hash_aset(rbce->headers, rb_str_new2("Expect"), rb_str_new2(""));
    }
  }
  else {
    rb_raise(rb_eRuntimeError, "PUT data must respond to read or to_s");
  }
  
  // if we made it this far, all should be well.
  return data;
}

#redirect_count ⇒ Integer

Retrieve the total number of redirections that were actually followed.

Requires libcurl 7.9.7 or higher, otherwise -1 is always returned.

Returns:

  • (Integer) 


2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
 
# File 'ext/curb_easy.c', line 2229

static VALUE ruby_curl_easy_redirect_count_get(VALUE self) {
#ifdef HAVE_CURLINFO_REDIRECT_COUNT
  ruby_curl_easy *rbce;
  long count;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_REDIRECT_COUNT, &count);

  return LONG2NUM(count);
#else
  rb_warn("Installed libcurl is too old to support redirect_count");
  return INT2FIX(-1);
#endif

}

#redirect_time ⇒ Float

Retrieve the total time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. redirect_time contains the complete execution time for multiple redirections.

Requires libcurl 7.9.7 or higher, otherwise -1 is always returned.

Returns:

  • (Float) 


2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
 
# File 'ext/curb_easy.c', line 2206

static VALUE ruby_curl_easy_redirect_time_get(VALUE self) {
#ifdef HAVE_CURLINFO_REDIRECT_TIME
  ruby_curl_easy *rbce;
  double time;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_REDIRECT_TIME, &time);

  return rb_float_new(time);
#else
  rb_warn("Installed libcurl is too old to support redirect_time");
  return rb_float_new(-1);
#endif
}

#request_size ⇒ Fixnum

Retrieve the total size of the issued requests. This is so far only for HTTP requests. Note that this may be more than one request if follow_location? is true.

Returns:

  • (Fixnum) 


2338
2339
2340
2341
2342
2343
2344
2345
2346
 
# File 'ext/curb_easy.c', line 2338

static VALUE ruby_curl_easy_request_size_get(VALUE self) {
  ruby_curl_easy *rbce;
  long size;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_REQUEST_SIZE, &size);

  return LONG2NUM(size);
}

#response_code ⇒ Fixnum

Retrieve the last received HTTP or FTP code. This will be zero if no server response code has been received. Note that a proxy’s CONNECT response should be read with http_connect_code and not this method.

Returns:

  • (Fixnum) 


2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
 
# File 'ext/curb_easy.c', line 2044

static VALUE ruby_curl_easy_response_code_get(VALUE self) {
  ruby_curl_easy *rbce;
  long code;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
#ifdef HAVE_CURLINFO_RESPONSE_CODE
  curl_easy_getinfo(rbce->curl, CURLINFO_RESPONSE_CODE, &code);
#else
  // old libcurl
  curl_easy_getinfo(rbce->curl, CURLINFO_HTTP_CODE, &code);
#endif

  return LONG2NUM(code);
}

#ssl_verify_host=(boolean) ⇒ Boolean

Configure whether this Curl instance will verify that the server cert is for the server it is known as. When true (the default) the server certificate must indicate that the server is the server to which you meant to connect, or the connection fails. When false, the connection will succeed regardless of the names in the certificate.

this option controls is of the identity that the server claims. The server could be lying. To control lying, see ssl_verify_peer? .

Returns:

  • (Boolean) 


1134
1135
1136
 
# File 'ext/curb_easy.c', line 1134

static VALUE ruby_curl_easy_ssl_verify_host_set(VALUE self, VALUE ssl_verify_host) {
  CURB_BOOLEAN_SETTER(ruby_curl_easy, ssl_verify_host);
}

#ssl_verify_host? ⇒ Boolean

Determine whether this Curl instance will verify that the server cert is for the server it is known as.

Returns:

  • (Boolean) 


1145
1146
1147
 
# File 'ext/curb_easy.c', line 1145

static VALUE ruby_curl_easy_ssl_verify_host_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, ssl_verify_host);
}

#ssl_verify_peer=(boolean) ⇒ Boolean

Configure whether this Curl instance will verify the SSL peer certificate. When true (the default), and the verification fails to prove that the certificate is authentic, the connection fails. When false, the connection succeeds regardless.

Authenticating the certificate is not by itself very useful. You typically want to ensure that the server, as authentically identified by its certificate, is the server you mean to be talking to. The ssl_verify_host? options controls that.

Returns:

  • (Boolean) 


1106
1107
1108
 
# File 'ext/curb_easy.c', line 1106

static VALUE ruby_curl_easy_ssl_verify_peer_set(VALUE self, VALUE ssl_verify_peer) {
  CURB_BOOLEAN_SETTER(ruby_curl_easy, ssl_verify_peer);
}

#ssl_verify_peer? ⇒ Boolean

Determine whether this Curl instance will verify the SSL peer certificate.

Returns:

  • (Boolean) 


1117
1118
1119
 
# File 'ext/curb_easy.c', line 1117

static VALUE ruby_curl_easy_ssl_verify_peer_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, ssl_verify_peer);
}

#ssl_verify_result ⇒ Integer

Retrieve the result of the certification verification that was requested (by setting ssl_verify_peer? to true).

Returns:

  • (Integer) 


2355
2356
2357
2358
2359
2360
2361
2362
2363
 
# File 'ext/curb_easy.c', line 2355

static VALUE ruby_curl_easy_ssl_verify_result_get(VALUE self) {
  ruby_curl_easy *rbce;
  long result;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_SSL_VERIFYRESULT, &result);

  return LONG2NUM(result);
}

#start_transfer_time ⇒ Float

Retrieve the time, in seconds, it took from the start until the first byte is just about to be transferred. This includes the pre_transfer_time and also the time the server needs to calculate the result.

Returns:

  • (Float) 


2185
2186
2187
2188
2189
2190
2191
2192
2193
 
# File 'ext/curb_easy.c', line 2185

static VALUE ruby_curl_easy_start_transfer_time_get(VALUE self) {
  ruby_curl_easy *rbce;
  double time;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_STARTTRANSFER_TIME, &time);

  return rb_float_new(time);
}

#timeout ⇒ Fixnum?

Obtain the maximum time in seconds that you allow the libcurl transfer operation to take.

Returns:

  • (Fixnum, nil) 


968
969
970
 
# File 'ext/curb_easy.c', line 968

static VALUE ruby_curl_easy_timeout_get(VALUE self, VALUE timeout) {
  CURB_IMMED_GETTER(ruby_curl_easy, timeout, 0);
}

#timeout=(fixnum) ⇒ Fixnum?

Set the maximum time in seconds that you allow the libcurl transfer operation to take. Normally, name lookups can take a considerable time and limiting operations to less than a few minutes risk aborting perfectly normal operations.

Set to nil (or zero) to disable timeout (it will then only timeout on the system’s internal timeouts).

Returns:

  • (Fixnum, nil) 


957
958
959
 
# File 'ext/curb_easy.c', line 957

static VALUE ruby_curl_easy_timeout_set(VALUE self, VALUE timeout) {
  CURB_IMMED_SETTER(ruby_curl_easy, timeout, 0);
}

#total_time ⇒ Float

Retrieve the total time in seconds for the previous transfer, including name resolving, TCP connect etc.

Returns:

  • (Float) 


2114
2115
2116
2117
2118
2119
2120
2121
2122
 
# File 'ext/curb_easy.c', line 2114

static VALUE ruby_curl_easy_total_time_get(VALUE self) {
  ruby_curl_easy *rbce;
  double time;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_TOTAL_TIME, &time);

  return rb_float_new(time);
}

#unescape("some text") ⇒ Object

Convert the given URL encoded input string to a “plain string” and return the result. All input characters that are URL encoded (%XX where XX is a two-digit hexadecimal number) are converted to their binary versions.



2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
 
# File 'ext/curb_easy.c', line 2597

static VALUE ruby_curl_easy_unescape(VALUE self, VALUE str) {
  ruby_curl_easy *rbce;
  int rlen;
  char *result;
  VALUE rresult;

  Data_Get_Struct(self, ruby_curl_easy, rbce);

#if (LIBCURL_VERSION_NUM >= 0x070f04)
  result = (char*)curl_easy_unescape(rbce->curl, StringValuePtr(str), RSTRING_LEN(str), &rlen);
#else
  result = (char*)curl_unescape(StringValuePtr(str), RSTRING_LEN(str));
  rlen = strlen(result);
#endif

  rresult = rb_str_new(result, rlen);
  curl_free(result);

  return rresult;
}

#unrestricted_auth=(boolean) ⇒ Boolean

Configure whether this Curl instance may use any HTTP authentication method available when necessary.

Returns:

  • (Boolean) 


1224
1225
1226
 
# File 'ext/curb_easy.c', line 1224

static VALUE ruby_curl_easy_unrestricted_auth_set(VALUE self, VALUE unrestricted_auth) {
  CURB_BOOLEAN_SETTER(ruby_curl_easy, unrestricted_auth);
}

#unrestricted_auth? ⇒ Boolean

Determine whether this Curl instance may use any HTTP authentication method available when necessary.

Returns:

  • (Boolean) 


1235
1236
1237
 
# File 'ext/curb_easy.c', line 1235

static VALUE ruby_curl_easy_unrestricted_auth_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, unrestricted_auth);
}

#upload_speed ⇒ Float

Retrieve the average upload speed that curl measured for the preceeding complete upload.

Returns:

  • (Float) 


2286
2287
2288
2289
2290
2291
2292
2293
2294
 
# File 'ext/curb_easy.c', line 2286

static VALUE ruby_curl_easy_upload_speed_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_SPEED_UPLOAD, &bytes);

  return rb_float_new(bytes);
}

#uploaded_bytes ⇒ Float

Retrieve the total amount of bytes that were uploaded in the preceeding transfer.

Returns:

  • (Float) 


2252
2253
2254
2255
2256
2257
2258
2259
2260
 
# File 'ext/curb_easy.c', line 2252

static VALUE ruby_curl_easy_uploaded_bytes_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_SIZE_UPLOAD, &bytes);

  return rb_float_new(bytes);
}

#uploaded_content_length ⇒ Float

Retrieve the content-length of the upload.

Returns:

  • (Float) 


2393
2394
2395
2396
2397
2398
2399
2400
2401
 
# File 'ext/curb_easy.c', line 2393

static VALUE ruby_curl_easy_uploaded_content_length_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_CONTENT_LENGTH_UPLOAD, &bytes);

  return rb_float_new(bytes);
}

#url ⇒ Object

Obtain the URL that will be used by subsequent calls to perform.



321
322
323
 
# File 'ext/curb_easy.c', line 321

static VALUE ruby_curl_easy_url_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, url);
}

#url=(url) ⇒ Object

Set the URL for subsequent calls to perform. It is acceptable (and even recommended) to reuse Curl::Easy instances by reassigning the URL between calls to perform.



311
312
313
 
# File 'ext/curb_easy.c', line 311

static VALUE ruby_curl_easy_url_set(VALUE self, VALUE url) {
  CURB_OBJECT_SETTER(ruby_curl_easy, url);
}

#use_netrc=(boolean) ⇒ Boolean

Configure whether this Curl instance will use data from the user’s .netrc file for FTP connections.

Returns:

  • (Boolean) 


1179
1180
1181
 
# File 'ext/curb_easy.c', line 1179

static VALUE ruby_curl_easy_use_netrc_set(VALUE self, VALUE use_netrc) {
  CURB_BOOLEAN_SETTER(ruby_curl_easy, use_netrc);
}

#use_netrc? ⇒ Boolean

Determine whether this Curl instance will use data from the user’s .netrc file for FTP connections.

Returns:

  • (Boolean) 


1190
1191
1192
 
# File 'ext/curb_easy.c', line 1190

static VALUE ruby_curl_easy_use_netrc_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, use_netrc);
}

#useragent ⇒ "Ruby/Curb"

Obtain the user agent string used for this Curl::Easy instance

Returns:

  • ("Ruby/Curb") 


652
653
654
 
# File 'ext/curb_easy.c', line 652

static VALUE ruby_curl_easy_useragent_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, useragent);
}

#useragent=(useragent) ⇒ Object

Set the user agent string for this Curl::Easy instance



642
643
644
 
# File 'ext/curb_easy.c', line 642

static VALUE ruby_curl_easy_useragent_set(VALUE self, VALUE useragent) {
  CURB_OBJECT_SETTER(ruby_curl_easy, useragent);
}

#userpwd ⇒ Object

Obtain the username/password string that will be used for subsequent calls to perform.



440
441
442
 
# File 'ext/curb_easy.c', line 440

static VALUE ruby_curl_easy_userpwd_get(VALUE self) {
  CURB_OBJECT_GETTER(ruby_curl_easy, userpwd);
}

#userpwd=(userpwd) ⇒ Object

Set the username/password string to use for subsequent calls to perform. The supplied string should have the form “username:password”



429
430
431
 
# File 'ext/curb_easy.c', line 429

static VALUE ruby_curl_easy_userpwd_set(VALUE self, VALUE userpwd) {
  CURB_OBJECT_SETTER(ruby_curl_easy, userpwd);
}

#verbose=(boolean) ⇒ Boolean

Configure whether this Curl instance gives verbose output to STDERR during transfers. Ignored if this instance has an on_debug handler.

Returns:

  • (Boolean) 


1246
1247
1248
 
# File 'ext/curb_easy.c', line 1246

static VALUE ruby_curl_easy_verbose_set(VALUE self, VALUE verbose) {
  CURB_BOOLEAN_SETTER(ruby_curl_easy, verbose);
}

#verbose? ⇒ Boolean

Determine whether this Curl instance gives verbose output to STDERR during transfers.

Returns:

  • (Boolean) 


1257
1258
1259
 
# File 'ext/curb_easy.c', line 1257

static VALUE ruby_curl_easy_verbose_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, verbose);
}