Class: Curl::Easy

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

Defined Under Namespace

Classes: Error

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

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

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

Overloads:

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

    Yields:

    • (self)


332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
# File 'ext/curb_easy.c', line 332

static VALUE ruby_curl_easy_initialize(int argc, VALUE *argv, VALUE self) {
  CURLcode ecode;
  VALUE url, blk;
  ruby_curl_easy *rbce;

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

  Data_Get_Struct(self, ruby_curl_easy, rbce);

  /* handler */
  rbce->curl = curl_easy_init();
  if (!rbce->curl) {
    rb_raise(eCurlErrFailedInit, "Failed to initialize easy handle");
  }

  rbce->multi = Qnil;
  rbce->opts  = Qnil;

  ruby_curl_easy_zero(rbce);

  rb_easy_set("url", url);


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

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

  return self;
}

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.



445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
# File 'lib/curl/easy.rb', line 445

def download(url, filename = url.split(/\?/).first.split(/\//).last, &blk)
  curl = Curl::Easy.new(url, &blk)

  output = if filename.is_a? IO
    filename.binmode if filename.respond_to?(:binmode)
    filename
  else
    File.open(filename, 'wb')
  end

  begin
    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
  ensure
    output.close rescue IOError
  end

  return curl
end

.Curl::Easy.error(code) ⇒ Array, String

translate an internal libcurl error to ruby error class

Returns ]

Returns:

  • (Array, String)

    ]



3706
3707
3708
# File 'ext/curb_easy.c', line 3706

static VALUE ruby_curl_easy_error_message(VALUE klass, VALUE code) {
  return rb_curl_easy_error(NUM2INT(code));
}

.http_delete(*args) {|c| ... } ⇒ Object

call-seq:

Curl::Easy.http_delete(url) { |easy| ... }       => #&lt;Curl::Easy...&gt;

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:

  • (c)


420
421
422
423
424
425
# File 'lib/curl/easy.rb', line 420

def http_delete(*args)
  c = Curl::Easy.new(*args)
  yield c if block_given?
  c.http_delete
  c
end

.http_get(*args) {|c| ... } ⇒ Object

call-seq:

Curl::Easy.http_get(url) { |easy| ... }          => #&lt;Curl::Easy...&gt;

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:

  • (c)


349
350
351
352
353
354
# File 'lib/curl/easy.rb', line 349

def http_get(*args)
  c = Curl::Easy.new(*args)
  yield c if block_given?
  c.http_get
  c
end

.http_head(*args) {|c| ... } ⇒ Object

call-seq:

Curl::Easy.http_head(url) { |easy| ... }         => #&lt;Curl::Easy...&gt;

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:

  • (c)


366
367
368
369
370
371
# File 'lib/curl/easy.rb', line 366

def http_head(*args)
  c = Curl::Easy.new(*args)
  yield c if block_given?
  c.http_head
  c
end

.http_post(*args) {|c| ... } ⇒ Object

call-seq:

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.

Yields:

  • (c)


402
403
404
405
406
407
408
# File 'lib/curl/easy.rb', line 402

def http_post(*args)
  url = args.shift
  c = Curl::Easy.new url
  yield c if block_given?
  c.http_post(*args)
  c
end

.http_put(url, data) {|c| ... } ⇒ Object

call-seq:

Curl::Easy.http_put(url, data) {|c| ... }

see easy.http_put

Yields:

  • (c)


379
380
381
382
383
384
# File 'lib/curl/easy.rb', line 379

def http_put(url, data)
  c = Curl::Easy.new url
  yield c if block_given?
  c.http_put data
  c
end

.perform(*args) {|c| ... } ⇒ Object

call-seq:

Curl::Easy.perform(url) { |easy| ... }           => #&lt;Curl::Easy...&gt;

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:

  • (c)


332
333
334
335
336
337
# File 'lib/curl/easy.rb', line 332

def perform(*args)
  c = Curl::Easy.new(*args)
  yield c if block_given?
  c.perform
  c
end

Instance Method Details

#app_connect_timeObject



2956
2957
2958
2959
2960
2961
2962
2963
2964
# File 'ext/curb_easy.c', line 2956

static VALUE ruby_curl_easy_app_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_APPCONNECT_TIME, &time);

  return rb_float_new(time);
}

#autoreferer=(autoreferer) ⇒ Object

easy = Curl::Easy.new easy.autoreferer=true



1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
# File 'ext/curb_easy.c', line 1745

static VALUE ruby_curl_easy_autoreferer_set(VALUE self, VALUE autoreferer) {
  ruby_curl_easy *rbce;
  Data_Get_Struct(self, ruby_curl_easy, rbce);

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

  return autoreferer;
}

#body_strObject Also known as: body

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.



2757
2758
2759
# File 'ext/curb_easy.c', line 2757

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

#cacertString

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

Returns:

  • (String)


708
709
710
# File 'ext/curb_easy.c', line 708

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

#cacert=(string) ⇒ Object

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



698
699
700
# File 'ext/curb_easy.c', line 698

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

#certString

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

Returns:

  • (String)


664
665
666
# File 'ext/curb_easy.c', line 664

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

#cert=(string) ⇒ Object

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



654
655
656
657
658
659
660
661
662
663
# File 'ext/curb_easy.c', line 654

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

#cert_keyObject

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



686
687
688
# File 'ext/curb_easy.c', line 686

static VALUE ruby_curl_easy_cert_key_get(VALUE self) {
  CURB_OBJECT_HGETTER(ruby_curl_easy, cert_key);
}

#cert_key=(cert_key) ⇒ Object

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



676
677
678
# File 'ext/curb_easy.c', line 676

static VALUE ruby_curl_easy_cert_key_set(VALUE self, VALUE cert_key) {
  CURB_OBJECT_HSETTER(ruby_curl_easy, cert_key);
}

#certpassword=(string) ⇒ Object

Set a password used to open the specified cert



718
719
720
# File 'ext/curb_easy.c', line 718

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

#certtypeString

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

Returns:

  • (String)


740
741
742
# File 'ext/curb_easy.c', line 740

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

#certtype=(certtype) ⇒ Object

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



730
731
732
# File 'ext/curb_easy.c', line 730

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

#cloneObject #dupObject Also known as: dup

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



376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
# File 'ext/curb_easy.c', line 376

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;
  newrbce->curl_proxy_headers = NULL;
  newrbce->curl_ftp_commands = NULL;
  newrbce->curl_resolve = NULL;

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

#closenil

Close the Curl::Easy instance. Any open connections are closed The easy handle is reinitialized. If a previous multi handle was open it is set to nil and will be cleared after a GC.

Returns:

  • (nil)


400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
# File 'ext/curb_easy.c', line 400

static VALUE ruby_curl_easy_close(VALUE self) {
  CURLcode ecode;
  ruby_curl_easy *rbce;

  Data_Get_Struct(self, ruby_curl_easy, rbce);

  if (rbce->callback_active) {
    rb_raise(rb_eRuntimeError, "Cannot close an active curl handle within a callback");
  }

  ruby_curl_easy_free(rbce);

  /* reinit the handle */
  rbce->curl = curl_easy_init();
  if (!rbce->curl) {
    rb_raise(eCurlErrFailedInit, "Failed to initialize easy handle");
  }

  rbce->multi = Qnil;

  ruby_curl_easy_zero(rbce);

  /* give the new curl handle a reference back to the ruby object */
  ecode = curl_easy_setopt(rbce->curl, CURLOPT_PRIVATE, (void*)self);
  if (ecode != CURLE_OK) {
    raise_curl_easy_error_exception(ecode);
  }

  return Qnil;
}

#connect_timeFloat

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

Returns:

  • (Float)


2935
2936
2937
2938
2939
2940
2941
2942
2943
# File 'ext/curb_easy.c', line 2935

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_timeoutFixnum?

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

Returns:

  • (Fixnum, nil)


1301
1302
1303
# File 'ext/curb_easy.c', line 1301

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)


1290
1291
1292
# File 'ext/curb_easy.c', line 1290

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

#connect_timeout_msFixnum?

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

Returns:

  • (Fixnum, nil)


1327
1328
1329
# File 'ext/curb_easy.c', line 1327

static VALUE ruby_curl_easy_connect_timeout_ms_get(VALUE self, VALUE connect_timeout_ms) {
  CURB_IMMED_GETTER(ruby_curl_easy, connect_timeout_ms, 0);
}

#connect_timeout_ms=(fixnum) ⇒ Fixnum?

Set the maximum time in milliseconds 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)


1316
1317
1318
# File 'ext/curb_easy.c', line 1316

static VALUE ruby_curl_easy_connect_timeout_ms_set(VALUE self, VALUE connect_timeout_ms) {
  CURB_IMMED_SETTER(ruby_curl_easy, connect_timeout_ms, 0);
}

#content_typenil

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)


3255
3256
3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
# File 'ext/curb_easy.c', line 3255

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;
  }
}

#cookiefileString

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

Returns:

  • (String)


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

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

#cookiefile=(value) ⇒ Object

call-seq:

easy.cookiefile = string                         => string

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.



235
236
237
# File 'lib/curl/easy.rb', line 235

def cookiefile=(value)
  set :cookiefile, value
end

#cookiejarString

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

Returns:

  • (String)


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

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

#cookiejar=(value) ⇒ Object

call-seq:

easy.cookiejar = string                          => string

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.



249
250
251
# File 'lib/curl/easy.rb', line 249

def cookiejar=(value)
  set :cookiejar, value
end

#cookielistArray

Retrieves the cookies curl knows in an array of strings. Returned strings are in Netscape cookiejar format or in Set-Cookie format.

See also option CURLINFO_COOKIELIST of curl_easy_getopt(3) to see how libcurl behaves.

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

Returns:

  • (Array)


3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
# File 'ext/curb_easy.c', line 3353

static VALUE ruby_curl_easy_cookielist_get(VALUE self) {
#ifdef HAVE_CURLINFO_COOKIELIST
  ruby_curl_easy *rbce;
  struct curl_slist *cookies;
  struct curl_slist *cookie;
  VALUE rb_cookies;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_COOKIELIST, &cookies);
  if (!cookies)
    return Qnil;
  rb_cookies = rb_ary_new();
  for (cookie = cookies; cookie; cookie = cookie->next)
    rb_ary_push(rb_cookies, rb_str_new2(cookie->data));
  curl_slist_free_all(cookies);
  return rb_cookies;

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

#cookiesObject

Obtain the cookies for this Curl::Easy instance.



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

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

#cookies=(value) ⇒ Object

call-seq:

easy.cookies = "name1=content1; name2=content2;" => string

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.



222
223
224
# File 'lib/curl/easy.rb', line 222

def cookies=(value)
  set :cookie, value
end

#deleteObject

call-seq:

easy.http_delete

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.



317
318
319
# File 'lib/curl/easy.rb', line 317

def http_delete
  self.http :DELETE
end

#delete=(onoff) ⇒ Object

call-seq:

easy = Curl::Easy.new("url") do|c|
 c.delete = true
end
easy.perform


102
103
104
105
# File 'lib/curl/easy.rb', line 102

def delete=(onoff)
  set :customrequest, onoff ? 'DELETE' : nil
  onoff
end

#dns_cache_timeoutFixnum?

Obtain the dns cache timeout in seconds.

Returns:

  • (Fixnum, nil)


1350
1351
1352
# File 'ext/curb_easy.c', line 1350

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)


1340
1341
1342
# File 'ext/curb_easy.c', line 1340

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_speedFloat

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

Returns:

  • (Float)


3143
3144
3145
3146
3147
3148
3149
3150
3151
# File 'ext/curb_easy.c', line 3143

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_bytesFloat

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

Returns:

  • (Float)


3109
3110
3111
3112
3113
3114
3115
3116
3117
# File 'ext/curb_easy.c', line 3109

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_lengthFloat

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

Returns:

  • (Float)


3220
3221
3222
3223
3224
3225
3226
3227
3228
# File 'ext/curb_easy.c', line 3220

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)


1850
1851
1852
1853
# File 'ext/curb_easy.c', line 1850

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)

Returns:

  • (Boolean)


1862
1863
1864
# File 'ext/curb_easy.c', line 1862

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

#encodingString

Get the set encoding types

Returns:

  • (String)


761
762
763
# File 'ext/curb_easy.c', line 761

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

#encoding=(string) ⇒ String

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

Returns:

  • (String)


751
752
753
# File 'ext/curb_easy.c', line 751

static VALUE ruby_curl_easy_encoding_set(VALUE self, VALUE encoding) {
  CURB_OBJECT_HSETTER(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).



3645
3646
3647
3648
3649
3650
3651
3652
3653
3654
3655
3656
3657
3658
3659
3660
3661
3662
3663
3664
3665
3666
# File 'ext/curb_easy.c', line 3645

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

  Data_Get_Struct(self, ruby_curl_easy, rbce);

  /* NOTE: make sure the value is a string, if not call to_s */
  if( rb_type(str) != T_STRING ) { str = rb_funcall(str,rb_intern("to_s"),0); }

#if (LIBCURL_VERSION_NUM >= 0x070f04)
  result = (char*)curl_easy_escape(rbce->curl, StringValuePtr(str), (int)RSTRING_LEN(str));
#else
  result = (char*)curl_escape(StringValuePtr(str), (int)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)


1622
1623
1624
# File 'ext/curb_easy.c', line 1622

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)

Returns:

  • (Boolean)


1633
1634
1635
# File 'ext/curb_easy.c', line 1633

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

#file_timeFixnum

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)


2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
# File 'ext/curb_easy.c', line 2879

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 LONG2NUM(0);
#endif
}

#follow_location=(onoff) ⇒ Object

call-seq:

easy.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.



272
273
274
# File 'lib/curl/easy.rb', line 272

def follow_location=(onoff)
  set :followlocation, onoff
end

#follow_location?Boolean

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

Returns:

  • (Boolean)

Returns:

  • (Boolean)


1766
1767
1768
# File 'ext/curb_easy.c', line 1766

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

#ftp_commandsObject

call-seq

easy.ftp_commands                                => array or nil


950
951
952
# File 'ext/curb_easy.c', line 950

static VALUE ruby_curl_easy_ftp_commands_get(VALUE self) {
  CURB_OBJECT_HGETTER(ruby_curl_easy, ftp_commands);
}

#ftp_commands=(ftp_commands) ⇒ Object

Explicitly sets the list of commands to execute on the FTP server when calling perform



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

static VALUE ruby_curl_easy_ftp_commands_set(VALUE self, VALUE ftp_commands) {
  CURB_OBJECT_HSETTER(ruby_curl_easy, ftp_commands);
}

#ftp_entry_pathnil

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)


3395
3396
3397
3398
3399
3400
3401
3402
3403
3404
3405
3406
3407
3408
3409
3410
3411
3412
# File 'ext/curb_easy.c', line 3395

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_filemethod(ftp_filemethod) ⇒ Object

call-seq

easy.ftp_filemethod                              => fixnum

Get the configuration for how libcurl will reach files on the server.



1589
1590
1591
# File 'ext/curb_easy.c', line 1589

static VALUE ruby_curl_easy_ftp_filemethod_get(VALUE self, VALUE ftp_filemethod) {
  CURB_IMMED_GETTER(ruby_curl_easy, ftp_filemethod, -1);
}

#ftp_filemethod=(value) ⇒ Fixnum?

Controls how libcurl reaches files on the server. Valid options are Curl::CURL_MULTICWD, Curl::CURL_NOCWD, and Curl::CURL_SINGLECWD (see libcurl docs for CURLOPT_FTP_METHOD).

Returns:

  • (Fixnum, nil)


1579
1580
1581
# File 'ext/curb_easy.c', line 1579

static VALUE ruby_curl_easy_ftp_filemethod_set(VALUE self, VALUE ftp_filemethod) {
  CURB_IMMED_SETTER(ruby_curl_easy, ftp_filemethod, -1);
}

#ftp_response_timeoutFixnum?

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

Returns:

  • (Fixnum, nil)


1377
1378
1379
# File 'ext/curb_easy.c', line 1377

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)


1367
1368
1369
# File 'ext/curb_easy.c', line 1367

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);
}

#getObject

call-seq:

easy.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.



304
305
306
307
# File 'lib/curl/easy.rb', line 304

def http_get
  set :httpget, true
  http :GET
end

#FixnumObject

Iniital access to libcurl curl_easy_getinfo, remember getinfo doesn't return the same values as setopt



3608
3609
3610
# File 'ext/curb_easy.c', line 3608

static VALUE ruby_curl_easy_get_opt(VALUE self, VALUE opt) {
  return Qnil;
}

#head=(onoff) ⇒ Object

call-seq:

easy = Curl::Easy.new("url") do|c|
 c.head = true
end
easy.perform


260
261
262
# File 'lib/curl/easy.rb', line 260

def head=(onoff)
  set :nobody, onoff
end

#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)


1702
1703
1704
# File 'ext/curb_easy.c', line 1702

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 return HTTP headers combined with body data.

Returns:

  • (Boolean)

Returns:

  • (Boolean)


1713
1714
1715
# File 'ext/curb_easy.c', line 1713

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

#header_sizeFixnum

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

Returns:

  • (Fixnum)


3160
3161
3162
3163
3164
3165
3166
3167
3168
# File 'ext/curb_easy.c', line 3160

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_strObject Also known as: head

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.



2769
2770
2771
# File 'ext/curb_easy.c', line 2769

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

#headersHash, ...

Obtain the custom HTTP headers for following requests.

Returns:

  • (Hash, Array, Str)


538
539
540
541
542
543
544
545
# File 'ext/curb_easy.c', line 538

static VALUE ruby_curl_easy_headers_get(VALUE self) {
  ruby_curl_easy *rbce;
  VALUE headers;
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  headers = rb_easy_get("headers");//rb_hash_aref(rbce->opts, rb_intern("headers"));
  if (headers == Qnil) { headers = rb_easy_set("headers", rb_hash_new()); }
  return headers;
}

#headers=(headers) ⇒ Object

easy.headers = => “val” …, “Header” => “val” => 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.



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

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

#http(verb) ⇒ Object

Send an HTTP request with method set to verb, 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.



2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
# File 'ext/curb_easy.c', line 2620

static VALUE ruby_curl_easy_perform_verb(VALUE self, VALUE verb) {
  VALUE str_verb;
  if (rb_type(verb) == T_STRING) {
    return ruby_curl_easy_perform_verb_str(self, StringValueCStr(verb));
  }
  else if (rb_respond_to(verb,rb_intern("to_s"))) {
    str_verb = rb_funcall(verb, rb_intern("to_s"), 0);
    return ruby_curl_easy_perform_verb_str(self, StringValueCStr(str_verb));
  }
  else {
    rb_raise(rb_eRuntimeError, "Invalid HTTP VERB, must response to 'to_s'");
  }
}

#http_auth_typesFixnum?

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

Returns:

  • (Fixnum, nil)


1142
1143
1144
# File 'ext/curb_easy.c', line 1142

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

#http_auth_types=(*args) ⇒ Object

VALUE self, VALUE http_auth_types) {



1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
# File 'ext/curb_easy.c', line 1101

static VALUE ruby_curl_easy_http_auth_types_set(int argc, VALUE *argv, VALUE self) {//VALUE self, VALUE http_auth_types) {
  ruby_curl_easy *rbce;
  VALUE args_ary;
  long i, len;
  char* node = NULL;
  long mask = 0;

  rb_scan_args(argc, argv, "*", &args_ary);
  Data_Get_Struct(self, ruby_curl_easy, rbce);

  len = RARRAY_LEN(args_ary);

  if (len == 1 && (rb_ary_entry(args_ary,0) == Qnil || TYPE(rb_ary_entry(args_ary,0)) == T_FIXNUM ||
        TYPE(rb_ary_entry(args_ary,0)) == T_BIGNUM)) {
    if (rb_ary_entry(args_ary,0) == Qnil) {
      rbce->http_auth_types = 0;
    }
    else {
      rbce->http_auth_types = NUM2LONG(rb_ary_entry(args_ary,0));
    }
  }
  else {
    // we could have multiple values, but they should be symbols
    node = RSTRING_PTR(rb_funcall(rb_ary_entry(args_ary,0),rb_intern("to_s"),0));
    mask = CURL_HTTPAUTH_STR_TO_NUM(node);
    for( i = 1; i < len; ++i ) {
      node = RSTRING_PTR(rb_funcall(rb_ary_entry(args_ary,i),rb_intern("to_s"),0));
      mask |= CURL_HTTPAUTH_STR_TO_NUM(node);
    }
    rbce->http_auth_types = mask;
  }
  return LONG2NUM(rbce->http_auth_types);
}

#http_connect_codeFixnum

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

Returns:

  • (Fixnum)


2852
2853
2854
2855
2856
2857
2858
2859
2860
# File 'ext/curb_easy.c', line 2852

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_deleteObject

call-seq:

easy.http_delete

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.



314
315
316
# File 'lib/curl/easy.rb', line 314

def http_delete
  self.http :DELETE
end

#http_getObject

call-seq:

easy.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.



300
301
302
303
# File 'lib/curl/easy.rb', line 300

def http_get
  set :httpget, true
  http :GET
end

#http_headObject

call-seq:

easy.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.



285
286
287
288
289
290
# File 'lib/curl/easy.rb', line 285

def http_head
  set :nobody, true
  ret = self.perform
  set :nobody, false
  ret
end

#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)


2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
# File 'ext/curb_easy.c', line 2658

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 = rbce->curl;

  curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, NULL);

  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 if (rb_type(argv[i]) == T_ARRAY) {
        // see: https://github.com/rvanlieshout/curb/commit/8bcdefddc0162484681ebd1a92d52a642666a445
        long c = 0, argv_len = RARRAY_LEN(argv[i]);
        for (; c < argv_len; ++c) {
          if (rb_obj_is_instance_of(rb_ary_entry(argv[i],c), cCurlPostField)) {
            append_to_form(rb_ary_entry(argv[i],c), &first, &last);
          } else {
            rb_raise(eCurlErrInvalidPostField, "You must use PostFields only with multipart form posts");
            return Qnil;
          }
        }
      } 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 = rb_funcall(self, rb_intern("perform"), 0);
    curl_formfree(first);

    return ret;
  } else {
    VALUE post_body = Qnil;
    /* TODO: check for PostField.file and raise error before to_s fails */
    if ((post_body = rb_funcall(args_ary, idJoin, 1, rbstrAmp)) == Qnil) {
      rb_raise(eCurlErrError, "Failed to join arguments");
      return Qnil;
    } else {
      /* if the function call above returns an empty string because no additional arguments were passed this makes sure
         a previously set easy.post_body = "arg=foo&bar=bin"  will be honored */
      if( post_body != Qnil && rb_type(post_body) == T_STRING && RSTRING_LEN(post_body) > 0 ) {
        ruby_curl_easy_post_body_set(self, post_body);
      }

      /* if post body is not defined, set it so we enable POST header, even though the request body is empty */
      if( rb_easy_nil("postdata_buffer") ) {
        ruby_curl_easy_post_body_set(self, post_body);
      }

      return rb_funcall(self, rb_intern("perform"), 0);
    }
  }
}

#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)


2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
# File 'ext/curb_easy.c', line 2733

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;

  curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, NULL);
  ruby_curl_easy_put_data_set(self, data);

  return rb_funcall(self, rb_intern("perform"), 0);
}

#ignore_content_length=(boolean) ⇒ Object

Configure whether this Curl::Easy instance should ignore the content length header.



1873
1874
1875
1876
# File 'ext/curb_easy.c', line 1873

static VALUE ruby_curl_easy_ignore_content_length_set(VALUE self, VALUE ignore_content_length)
{
  CURB_BOOLEAN_SETTER(ruby_curl_easy, ignore_content_length);
}

#ignore_content_length?Boolean

Determine whether this Curl::Easy instance ignores the content length header.

Returns:

  • (Boolean)

Returns:

  • (Boolean)


1885
1886
1887
# File 'ext/curb_easy.c', line 1885

static VALUE ruby_curl_easy_ignore_content_length_q(VALUE self) {
  CURB_BOOLEAN_GETTER(ruby_curl_easy, ignore_content_length);
}

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

Returns:



3616
3617
3618
3619
3620
3621
3622
3623
3624
3625
3626
3627
3628
3629
3630
3631
# File 'ext/curb_easy.c', line 3616

static VALUE ruby_curl_easy_inspect(VALUE self) {
  char buf[64];
  ruby_curl_easy *rbce;
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  /* if we don't have a url set... we'll crash... */
  if( !rb_easy_nil("url") && rb_easy_type_check("url", T_STRING)) {
    VALUE url = rb_easy_get("url");
    size_t len = 13+((RSTRING_LEN(url) > 50) ? 50 : RSTRING_LEN(url));
    /* "#<Net::HTTP http://www.google.com/:80 open=false>" */
    memcpy(buf,"#<Curl::Easy ", 13);
    memcpy(buf+13,StringValueCStr(url), (len - 13));
    buf[len++] = '>';
    return rb_str_new(buf,len);
  }
  return rb_str_new2("#<Curl::Easy>");
}

#interfaceString

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.

Returns:

  • (String)


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

static VALUE ruby_curl_easy_interface_get(VALUE self) {
  CURB_OBJECT_HGETTER(ruby_curl_easy, interface_hm);
}

#interface=(value) ⇒ Object

call-seq:

easy.interface = string                          => string

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.



187
188
189
# File 'lib/curl/easy.rb', line 187

def interface=(value)
  set :interface, value
end

#last_effective_urlnil

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)


2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
# File 'ext/curb_easy.c', line 2784

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;
  }
}

#last_result0

Returns:

  • (0)


3439
3440
3441
3442
3443
# File 'ext/curb_easy.c', line 3439

static VALUE ruby_curl_easy_last_result(VALUE self) {
  ruby_curl_easy *rbce;
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  return LONG2NUM(rbce->last_result);
}

#local_portFixnum?

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)


998
999
1000
# File 'ext/curb_easy.c', line 998

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)


986
987
988
# File 'ext/curb_easy.c', line 986

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_rangeFixnum?

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)


1029
1030
1031
# File 'ext/curb_easy.c', line 1029

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)


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

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");
}

#low_speed_limitFixnum?

Obtain the minimum transfer speed over low_speedtime+ below which the transfer will be aborted.

Returns:

  • (Fixnum, nil)


1400
1401
1402
# File 'ext/curb_easy.c', line 1400

static VALUE ruby_curl_easy_low_speed_limit_get(VALUE self, VALUE low_speed_limit) {
  CURB_IMMED_GETTER(ruby_curl_easy, low_speed_limit, 0);
}

#low_speed_limit=(fixnum) ⇒ Fixnum?

Set the transfer speed (in bytes per second) that the transfer should be below during low_speed_time seconds for the library to consider it too slow and abort.

Returns:

  • (Fixnum, nil)


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

static VALUE ruby_curl_easy_low_speed_limit_set(VALUE self, VALUE low_speed_limit) {
  CURB_IMMED_SETTER(ruby_curl_easy, low_speed_limit, 0);
}

#low_speed_timeFixnum?

Obtain the time that the transfer should be below low_speed_limit for the library to abort it.

Returns:

  • (Fixnum, nil)


1422
1423
1424
# File 'ext/curb_easy.c', line 1422

static VALUE ruby_curl_easy_low_speed_time_get(VALUE self, VALUE low_speed_time) {
  CURB_IMMED_GETTER(ruby_curl_easy, low_speed_time, 0);
}

#low_speed_time=(fixnum) ⇒ Fixnum?

Set the time (in seconds) that the transfer should be below the low_speed_limit for the library to consider it too slow and abort.

Returns:

  • (Fixnum, nil)


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

static VALUE ruby_curl_easy_low_speed_time_set(VALUE self, VALUE low_speed_time) {
  CURB_IMMED_SETTER(ruby_curl_easy, low_speed_time, 0);
}

#max_recv_speed_large=(fixnum) ⇒ Fixnum?

Get the maximal receiving transfer speed (in bytes per second)

Returns:

  • (Fixnum, nil)


1462
1463
1464
# File 'ext/curb_easy.c', line 1462

static VALUE ruby_curl_easy_max_recv_speed_large_get(VALUE self, VALUE max_recv_speed_large) {
  CURB_IMMED_GETTER(ruby_curl_easy, max_recv_speed_large, 0);
}

#max_recv_speed_large=(fixnum) ⇒ Fixnum?

Set the maximal receiving transfer speed (in bytes per second)

Returns:

  • (Fixnum, nil)


1452
1453
1454
# File 'ext/curb_easy.c', line 1452

static VALUE ruby_curl_easy_max_recv_speed_large_set(VALUE self, VALUE max_recv_speed_large) {
  CURB_IMMED_SETTER(ruby_curl_easy, max_recv_speed_large, 0);
}

#max_redirectsFixnum?

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

Returns:

  • (Fixnum, nil)


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

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)


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

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

#max_send_speed_large=(fixnum) ⇒ Fixnum?

Get the maximal sending transfer speed (in bytes per second)

Returns:

  • (Fixnum, nil)


1442
1443
1444
# File 'ext/curb_easy.c', line 1442

static VALUE ruby_curl_easy_max_send_speed_large_get(VALUE self, VALUE max_send_speed_large) {
  CURB_IMMED_GETTER(ruby_curl_easy, max_send_speed_large, 0);
}

#max_send_speed_large=(fixnum) ⇒ Fixnum?

Set the maximal sending transfer speed (in bytes per second)

Returns:

  • (Fixnum, nil)


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

static VALUE ruby_curl_easy_max_send_speed_large_set(VALUE self, VALUE max_send_speed_large) {
  CURB_IMMED_SETTER(ruby_curl_easy, max_send_speed_large, 0);
}

#multi"#<Curl::Multi>"

Returns:



3418
3419
3420
3421
3422
# File 'ext/curb_easy.c', line 3418

static VALUE ruby_curl_easy_multi_get(VALUE self) {
  ruby_curl_easy *rbce;
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  return rbce->multi;
}

#multi="#<Curl::Multi>"

Returns:



3428
3429
3430
3431
3432
3433
# File 'ext/curb_easy.c', line 3428

static VALUE ruby_curl_easy_multi_set(VALUE self, VALUE multi) {
  ruby_curl_easy *rbce;
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  rbce->multi = multi;
  return rbce->multi;
}

#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)


1827
1828
1829
1830
# File 'ext/curb_easy.c', line 1827

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)

Returns:

  • (Boolean)


1839
1840
1841
# File 'ext/curb_easy.c', line 1839

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

#name_lookup_timeFloat

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

Returns:

  • (Float)


2918
2919
2920
2921
2922
2923
2924
2925
2926
# File 'ext/curb_easy.c', line 2918

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



474
# File 'lib/curl/easy.rb', line 474

alias_method :native_cert=, :cert=

#nosignal=(onoff) ⇒ Object

call-seq:

easy = Curl::Easy.new easy.nosignal = true



91
92
93
# File 'lib/curl/easy.rb', line 91

def nosignal=(onoff)
  set :nosignal, !!onoff
end

#num_connectsInteger

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)


3326
3327
3328
3329
3330
3331
3332
3333
3334
3335
3336
3337
3338
3339
# File 'ext/curb_easy.c', line 3326

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 LONG2NUM(-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)


1969
1970
1971
# File 'ext/curb_easy.c', line 1969

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

#on_complete {|easy| ... } ⇒ 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:

  • (easy)


2043
2044
2045
# File 'ext/curb_easy.c', line 2043

static VALUE ruby_curl_easy_on_complete_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_HSETTER(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)


2101
2102
2103
# File 'ext/curb_easy.c', line 2101

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

#on_failure {|easy, code| ... } ⇒ 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:

  • (easy, code)


1999
2000
2001
# File 'ext/curb_easy.c', line 1999

static VALUE ruby_curl_easy_on_failure_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_HSETTER(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)


2059
2060
2061
# File 'ext/curb_easy.c', line 2059

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

#on_missing {|easy, code| ... } ⇒ Object

Assign or remove the on_missing handler for this Curl::Easy instance.

To remove a previously-supplied handler, call this method with no attached
block.

The +on_missing+ handler is called when request is finished with a
status of 40x

Yields:

  • (easy, code)


2014
2015
2016
# File 'ext/curb_easy.c', line 2014

static VALUE ruby_curl_easy_on_missing_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_HSETTER(ruby_curl_easy, missing_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)


2080
2081
2082
# File 'ext/curb_easy.c', line 2080

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

#on_redirect {|easy, code| ... } ⇒ Object

Assign or remove the on_redirect handler for this Curl::Easy instance.

To remove a previously-supplied handler, call this method with no attached
block.

The +on_redirect+ handler is called when request is finished with a
status of 30x

Yields:

  • (easy, code)


2029
2030
2031
# File 'ext/curb_easy.c', line 2029

static VALUE ruby_curl_easy_on_redirect_set(int argc, VALUE *argv, VALUE self) {
  CURB_HANDLER_PROC_HSETTER(ruby_curl_easy, redirect_proc);
}

#on_success {|easy| ... } ⇒ 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:

  • (easy)


1984
1985
1986
# File 'ext/curb_easy.c', line 1984

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

#os_errnoInteger

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

Returns:

  • (Integer)


3297
3298
3299
3300
3301
3302
3303
3304
3305
3306
3307
3308
3309
3310
# File 'ext/curb_easy.c', line 3297

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 LONG2NUM(0);
#endif
}

#passwordString

Get the current password

Returns:

  • (String)


1514
1515
1516
1517
1518
1519
1520
# File 'ext/curb_easy.c', line 1514

static VALUE ruby_curl_easy_password_get(VALUE self, VALUE password) {
#if HAVE_CURLOPT_PASSWORD
  CURB_OBJECT_HGETTER(ruby_curl_easy, password);
#else
  return Qnil;
#endif
}

#password=(string) ⇒ String

Set the HTTP Authentication password.

Returns:

  • (String)


1500
1501
1502
1503
1504
1505
1506
# File 'ext/curb_easy.c', line 1500

static VALUE ruby_curl_easy_password_set(VALUE self, VALUE password) {
#if HAVE_CURLOPT_PASSWORD
  CURB_OBJECT_HSETTER(ruby_curl_easy, password);
#else
  return Qnil;
#endif
}

#performObject

call-seq:

easy.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 configured HTTP Verb.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
# File 'lib/curl/easy.rb', line 66

def perform
  self.multi = Curl::Multi.new if self.multi.nil?
  self.multi.add self
  ret = self.multi.perform
  self.multi.remove self

  if Curl::Multi.autoclose
    self.multi.close
    self.multi = nil
  end

  if self.last_result != 0 && self.on_failure.nil?
    error = Curl::Easy.error(self.last_result)
    raise error.first.new(self.head)
  end

  ret
end

#postObject



5
# File 'lib/curl/easy.rb', line 5

alias post http_post

#post_bodyString?

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

Returns:

  • (String, nil)


846
847
848
# File 'ext/curb_easy.c', line 846

static VALUE ruby_curl_easy_post_body_get(VALUE self) {
  CURB_OBJECT_HGETTER(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.



796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
# File 'ext/curb_easy.c', line 796

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 ) {
    rb_easy_del("postdata_buffer");
    curl_easy_setopt(curl, CURLOPT_HTTPGET, 1);

  } else {
    if (rb_type(post_body) == T_STRING) {
      data = StringValuePtr(post_body);
      len = RSTRING_LEN(post_body);
    }
    else if (rb_respond_to(post_body, rb_intern("to_s"))) {
      VALUE str_body = rb_funcall(post_body, rb_intern("to_s"), 0);
      data = StringValuePtr(str_body);
      len = RSTRING_LEN(post_body);
    }
    else {
      rb_raise(rb_eRuntimeError, "post data must respond_to .to_s");
    }

    // 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;
    rb_easy_set("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_timeFloat

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)


2977
2978
2979
2980
2981
2982
2983
2984
2985
# File 'ext/curb_easy.c', line 2977

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);
}

#primary_ipnil

Retrieve the resolved IP of the most recent connection

done with this curl handle. This string may be  IPv6 if
that's enabled. This feature requires curl 7.19.x and above

Returns:

  • (nil)


2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
# File 'ext/curb_easy.c', line 2831

static VALUE ruby_curl_easy_primary_ip_get(VALUE self) {
  ruby_curl_easy *rbce;
  char* ip;

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl_easy_getinfo(rbce->curl, CURLINFO_PRIMARY_IP, &ip);

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

#proxy_auth_typesFixnum?

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

Returns:

  • (Fixnum, nil)


1165
1166
1167
# File 'ext/curb_easy.c', line 1165

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)


1154
1155
1156
# File 'ext/curb_easy.c', line 1154

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_headersHash, ...

Obtain the custom HTTP proxy_headers for following requests.

Returns:

  • (Hash, Array, Str)


573
574
575
576
577
578
579
580
# File 'ext/curb_easy.c', line 573

static VALUE ruby_curl_easy_proxy_headers_get(VALUE self) {
  ruby_curl_easy *rbce;
  VALUE proxy_headers;
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  proxy_headers = rb_easy_get("proxy_headers");//rb_hash_aref(rbce->opts, rb_intern("proxy_headers"));
  if (proxy_headers == Qnil) { proxy_headers = rb_easy_set("proxy_headers", rb_hash_new()); }
  return proxy_headers;
}

#proxy_headers=(proxy_headers) ⇒ Object



528
529
530
# File 'ext/curb_easy.c', line 528

static VALUE ruby_curl_easy_proxy_headers_set(VALUE self, VALUE proxy_headers) {
  CURB_OBJECT_HSETTER(ruby_curl_easy, proxy_headers);
}

#proxy_portFixnum?

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

Returns:

  • (Fixnum, nil)


1049
1050
1051
# File 'ext/curb_easy.c', line 1049

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)


1039
1040
1041
# File 'ext/curb_easy.c', line 1039

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)


1601
1602
1603
# File 'ext/curb_easy.c', line 1601

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)

Returns:

  • (Boolean)


1611
1612
1613
# File 'ext/curb_easy.c', line 1611

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

#proxy_typeFixnum?

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

Returns:

  • (Fixnum, nil)


1070
1071
1072
# File 'ext/curb_easy.c', line 1070

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)


1060
1061
1062
# File 'ext/curb_easy.c', line 1060

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

#proxy_urlString

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

Returns:

  • (String)


498
499
500
# File 'ext/curb_easy.c', line 498

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

#proxy_url=(url) ⇒ Object

call-seq:

easy.proxy_url = string                          => string

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.



156
157
158
# File 'lib/curl/easy.rb', line 156

def proxy_url=(url)
  set :proxy, url
end

#proxypwdString

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”

Returns:

  • (String)


612
613
614
# File 'ext/curb_easy.c', line 612

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

#proxypwd=(value) ⇒ Object

call-seq:

easy.proxypwd = string                           => string

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



210
211
212
# File 'lib/curl/easy.rb', line 210

def proxypwd=(value)
  set :proxyuserpwd, value
end

#putObject



6
# File 'lib/curl/easy.rb', line 6

alias put http_put

#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.



858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
# File 'ext/curb_easy.c', line 858

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

  Data_Get_Struct(self, ruby_curl_easy, rbce);

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

  curl = rbce->curl;
  rb_easy_set("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);
#if HAVE_CURLOPT_SEEKFUNCTION
  curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, (curl_seek_callback)seek_data_handler);
#endif
  curl_easy_setopt(curl, CURLOPT_READDATA, rbce);
#if HAVE_CURLOPT_SEEKDATA
  curl_easy_setopt(curl, CURLOPT_SEEKDATA, rbce);
#endif

  /*
   * 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 (!rb_easy_nil("headers")) {
    if (rb_easy_type_check("headers", T_ARRAY) || rb_easy_type_check("headers", T_STRING)) {
      rb_raise(rb_eRuntimeError, "Must set headers as a HASH to modify the headers in an PUT request");
    }
  }

  // exit fast if the payload is empty
  if (NIL_P(data)) { return data; }

  headers = rb_easy_get("headers");
  if( headers == Qnil ) {
    headers = rb_hash_new();
  }

  if (rb_respond_to(data, rb_intern("read"))) {
    VALUE stat = rb_funcall(data, rb_intern("stat"), 0);
    if( stat && rb_hash_aref(headers, rb_str_new2("Content-Length")) == Qnil) {
      VALUE size;
      if( rb_hash_aref(headers, rb_str_new2("Expect")) == Qnil ) {
        rb_hash_aset(headers, rb_str_new2("Expect"), rb_str_new2(""));
      }
      size = rb_funcall(stat, rb_intern("size"), 0);
      curl_easy_setopt(curl, CURLOPT_INFILESIZE, NUM2LONG(size));
    }
    else if( rb_hash_aref(headers, rb_str_new2("Content-Length")) == Qnil && rb_hash_aref(headers, rb_str_new2("Transfer-Encoding")) == Qnil ) {
      rb_hash_aset(headers, rb_str_new2("Transfer-Encoding"), rb_str_new2("chunked"));
    }
    else if( rb_hash_aref(headers, rb_str_new2("Content-Length")) ) {
      VALUE size = rb_funcall(rb_hash_aref(headers, rb_str_new2("Content-Length")), rb_intern("to_i"), 0);
      curl_easy_setopt(curl, CURLOPT_INFILESIZE, NUM2LONG(size));
    }
  }
  else if (rb_respond_to(data, rb_intern("to_s"))) {
    curl_easy_setopt(curl, CURLOPT_INFILESIZE, RSTRING_LEN(data));
    if( rb_hash_aref(headers, rb_str_new2("Expect")) == Qnil ) {
      rb_hash_aset(headers, rb_str_new2("Expect"), rb_str_new2(""));
    }
  }
  else {
    rb_raise(rb_eRuntimeError, "PUT data must respond to read or to_s");
  }
  rb_easy_set("headers",headers);

  // if we made it this far, all should be well.
  return data;
}

#redirect_countInteger

Retrieve the total number of redirections that were actually followed.

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

Returns:

  • (Integer)


3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
# File 'ext/curb_easy.c', line 3039

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 LONG2NUM(-1);
#endif

}

#redirect_timeFloat

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)


3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
# File 'ext/curb_easy.c', line 3016

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
}

#redirect_urlnil

Retrieve the URL a redirect would take you to if you would enable CURLOPT_FOLLOWLOCATION.

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

Returns:

  • (nil)


3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
# File 'ext/curb_easy.c', line 3064

static VALUE ruby_curl_easy_redirect_url_get(VALUE self) {
#ifdef HAVE_CURLINFO_REDIRECT_URL
  ruby_curl_easy *rbce;
  char* url;

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

  if (url && url[0]) {    // curl returns empty string if none
    return rb_str_new2(url);
  } else {
    return Qnil;
  }
#else
  rb_warn("Installed libcurl is too old to support redirect_url");
  return LONG2NUM(-1);
#endif
}

#request_sizeFixnum

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)


3178
3179
3180
3181
3182
3183
3184
3185
3186
# File 'ext/curb_easy.c', line 3178

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);
}

#resetHash

Reset the Curl::Easy instance, clears out all settings.

from curl.haxx.se/libcurl/c/curl_easy_reset.html Re-initializes all options previously set on a specified CURL handle to the default values. This puts back the handle to the same state as it was in when it was just created with curl_easy_init(3). It does not change the following information kept in the handle: live connections, the Session ID cache, the DNS cache, the cookies and shares.

The return value contains all settings stored.

Returns:

  • (Hash)


443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
# File 'ext/curb_easy.c', line 443

static VALUE ruby_curl_easy_reset(VALUE self) {
  CURLcode ecode;
  ruby_curl_easy *rbce;
  VALUE opts_dup;
  Data_Get_Struct(self, ruby_curl_easy, rbce);

  if (rbce->callback_active) {
    rb_raise(rb_eRuntimeError, "Cannot close an active curl handle within a callback");
  }

  opts_dup = rb_funcall(rbce->opts, rb_intern("dup"), 0);

  curl_easy_reset(rbce->curl);
  ruby_curl_easy_zero(rbce);

  /* rest clobbers the private setting, so reset it to self */
  ecode = curl_easy_setopt(rbce->curl, CURLOPT_PRIVATE, (void*)self);
  if (ecode != CURLE_OK) {
    raise_curl_easy_error_exception(ecode);
  }

  /* Free everything up */
  if (rbce->curl_headers) {
    curl_slist_free_all(rbce->curl_headers);
    rbce->curl_headers = NULL;
  }

  /* Free everything up */
  if (rbce->curl_proxy_headers) {
    curl_slist_free_all(rbce->curl_proxy_headers);
    rbce->curl_proxy_headers = NULL;
  }

  return opts_dup;
}

#resolveObject

call-seq

easy.resolve                                => array or nil


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

static VALUE ruby_curl_easy_resolve_get(VALUE self) {
  CURB_OBJECT_HGETTER(ruby_curl_easy, resolve);
}

#resolve=(resolve) ⇒ Object

Set the resolve list to statically resolve hostnames to IP addresses, bypassing DNS for matching hostname/port combinations.



961
962
963
# File 'ext/curb_easy.c', line 961

static VALUE ruby_curl_easy_resolve_set(VALUE self, VALUE resolve) {
  CURB_OBJECT_HSETTER(ruby_curl_easy, resolve);
}

#resolve_modeObject

Determines what type of IP address this Curl::Easy instance resolves DNS names to.



1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
# File 'ext/curb_easy.c', line 1896

static VALUE ruby_curl_easy_resolve_mode(VALUE self) {
  ruby_curl_easy *rbce;
  unsigned short rm;
  Data_Get_Struct(self, ruby_curl_easy, rbce);

  rm = rbce->resolve_mode;

  switch(rm) {
    case CURL_IPRESOLVE_V4:
      return rb_easy_sym("ipv4");
    case CURL_IPRESOLVE_V6:
      return rb_easy_sym("ipv6");
    default:
      return rb_easy_sym("auto");
  }
}

#resolve_mode=(symbol) ⇒ Object

Configures what type of IP address this Curl::Easy instance resolves DNS names to. Valid options are:

:auto

resolves DNS names to all IP versions your system allows

:ipv4

resolves DNS names to IPv4 only

:ipv6

resolves DNS names to IPv6 only



1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
# File 'ext/curb_easy.c', line 1924

static VALUE ruby_curl_easy_resolve_mode_set(VALUE self, VALUE resolve_mode) {
  if (TYPE(resolve_mode) != T_SYMBOL) {
    rb_raise(rb_eTypeError, "Must pass a symbol");
    return Qnil;
  } else {
    ruby_curl_easy *rbce;
    ID resolve_mode_id;
    Data_Get_Struct(self, ruby_curl_easy, rbce);

    resolve_mode_id = rb_to_id(resolve_mode);

    if (resolve_mode_id == rb_intern("auto")) {
      rbce->resolve_mode = CURL_IPRESOLVE_WHATEVER;
      return resolve_mode;
    } else if (resolve_mode_id == rb_intern("ipv4")) {
      rbce->resolve_mode = CURL_IPRESOLVE_V4;
      return resolve_mode;
    } else if (resolve_mode_id == rb_intern("ipv6")) {
      rbce->resolve_mode = CURL_IPRESOLVE_V6;
      return resolve_mode;
    } else {
      rb_raise(rb_eArgError, "Must set to one of :auto, :ipv4, :ipv6");
      return Qnil;
    }
  }
}

#response_codeFixnum

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)


2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
# File 'ext/curb_easy.c', line 2807

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);
}

#set(opt, val) ⇒ Object

call-seq:

easy.set :sym|Fixnum, value

set options on the curl easy handle see curl.haxx.se/libcurl/c/curl_easy_setopt.html



34
35
36
37
38
39
40
41
42
43
44
45
46
# File 'lib/curl/easy.rb', line 34

def set(opt,val)
  if opt.is_a?(Symbol)
    option = sym2curl(opt)
  else
    option = opt.to_i
  end

  begin
    setopt(option, val)
  rescue TypeError
    raise TypeError, "Curb doesn't support setting #{opt} [##{option}] option"
  end
end

#FixnumObject

Initial access to libcurl curl_easy_setopt



3451
3452
3453
3454
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
3472
3473
3474
3475
3476
3477
3478
3479
3480
3481
3482
3483
3484
3485
3486
3487
3488
3489
3490
3491
3492
3493
3494
3495
3496
3497
3498
3499
3500
3501
3502
3503
3504
3505
3506
3507
3508
3509
3510
3511
3512
3513
3514
3515
3516
3517
3518
3519
3520
3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
3531
3532
3533
3534
3535
3536
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
3560
3561
3562
3563
3564
3565
3566
3567
3568
3569
3570
3571
3572
3573
3574
3575
3576
3577
3578
3579
3580
3581
3582
3583
3584
3585
3586
3587
3588
3589
3590
3591
3592
3593
3594
3595
3596
3597
3598
3599
3600
# File 'ext/curb_easy.c', line 3451

static VALUE ruby_curl_easy_set_opt(VALUE self, VALUE opt, VALUE val) {
  ruby_curl_easy *rbce;
  long option = NUM2LONG(opt);

  Data_Get_Struct(self, ruby_curl_easy, rbce);

  switch (option) {
  /* BEHAVIOR OPTIONS */
  case CURLOPT_VERBOSE: {
    VALUE verbose = val;
    CURB_BOOLEAN_SETTER(ruby_curl_easy, verbose);
    } break;
  case CURLOPT_FOLLOWLOCATION: {
    VALUE follow_location = val;
    CURB_BOOLEAN_SETTER(ruby_curl_easy, follow_location);
    } break;
  /* TODO: CALLBACK OPTIONS */
  /* TODO: ERROR OPTIONS */
  /* NETWORK OPTIONS */
  case CURLOPT_URL: {
    VALUE url = val;
    CURB_OBJECT_HSETTER(ruby_curl_easy, url);
    } break;
  case CURLOPT_CUSTOMREQUEST:
    curl_easy_setopt(rbce->curl, CURLOPT_CUSTOMREQUEST, NIL_P(val) ? NULL : StringValueCStr(val));
    break;
  case CURLOPT_HTTP_VERSION:
    curl_easy_setopt(rbce->curl, CURLOPT_HTTP_VERSION, NUM2LONG(val));
    break;
  case CURLOPT_PROXY: {
    VALUE proxy_url = val;
    CURB_OBJECT_HSETTER(ruby_curl_easy, proxy_url);
    } break;
  case CURLOPT_INTERFACE: {
    VALUE interface_hm = val;
    CURB_OBJECT_HSETTER(ruby_curl_easy, interface_hm);
    } break;
  case CURLOPT_HEADER:
  case CURLOPT_NOPROGRESS:
  case CURLOPT_NOSIGNAL:
#if HAVE_CURLOPT_PATH_AS_IS
  case CURLOPT_PATH_AS_IS:
#endif
#if HAVE_CURLOPT_PIPEWAIT
  case CURLOPT_PIPEWAIT:
#endif
  case CURLOPT_HTTPGET:
  case CURLOPT_NOBODY: {
    int type = rb_type(val);
    VALUE value;
    if (type == T_TRUE) {
      value = rb_int_new(1);
    } else if (type == T_FALSE) {
      value = rb_int_new(0);
    } else {
      value = rb_funcall(val, rb_intern("to_i"), 0);
    }
    curl_easy_setopt(rbce->curl, option, NUM2LONG(value));
    } break;
  case CURLOPT_POST: {
    curl_easy_setopt(rbce->curl, CURLOPT_POST, rb_type(val) == T_TRUE);
  } break;
  case CURLOPT_MAXCONNECTS: {
    curl_easy_setopt(rbce->curl, CURLOPT_MAXCONNECTS, NUM2LONG(val));
  } break;
  case CURLOPT_POSTFIELDS: {
    curl_easy_setopt(rbce->curl, CURLOPT_POSTFIELDS, NIL_P(val) ? NULL : StringValueCStr(val));
  } break;
  case CURLOPT_USERPWD: {
    VALUE userpwd = val;
    CURB_OBJECT_HSETTER(ruby_curl_easy, userpwd);
    } break;
  case CURLOPT_PROXYUSERPWD: {
    VALUE proxypwd = val;
    CURB_OBJECT_HSETTER(ruby_curl_easy, proxypwd);
    } break;
  case CURLOPT_COOKIE: {
    VALUE cookies = val;
    CURB_OBJECT_HSETTER(ruby_curl_easy, cookies);
    } break;
  case CURLOPT_COOKIEFILE: {
    VALUE cookiefile = val;
    CURB_OBJECT_HSETTER(ruby_curl_easy, cookiefile);
    } break;
  case CURLOPT_COOKIEJAR: {
    VALUE cookiejar = val;
    CURB_OBJECT_HSETTER(ruby_curl_easy, cookiejar);
    } break;
  case CURLOPT_TCP_NODELAY: {
    curl_easy_setopt(rbce->curl, CURLOPT_TCP_NODELAY, NUM2LONG(val));
    } break;
  case CURLOPT_RESUME_FROM: {
    curl_easy_setopt(rbce->curl, CURLOPT_RESUME_FROM, NUM2LONG(val));
    } break;
  case CURLOPT_FAILONERROR: {
    curl_easy_setopt(rbce->curl, CURLOPT_FAILONERROR, NUM2LONG(val));
    } break;
  case CURLOPT_SSL_CIPHER_LIST: {
    curl_easy_setopt(rbce->curl, CURLOPT_SSL_CIPHER_LIST, StringValueCStr(val));
    } break;
  case CURLOPT_FORBID_REUSE: {
    curl_easy_setopt(rbce->curl, CURLOPT_FORBID_REUSE, NUM2LONG(val));
    } break;
#if HAVE_CURLOPT_GSSAPI_DELEGATION
  case CURLOPT_GSSAPI_DELEGATION: {
    curl_easy_setopt(rbce->curl, CURLOPT_GSSAPI_DELEGATION, NUM2LONG(val));
    } break;
#endif
#if HAVE_CURLOPT_UNIX_SOCKET_PATH
  case CURLOPT_UNIX_SOCKET_PATH: {
	curl_easy_setopt(rbce->curl, CURLOPT_UNIX_SOCKET_PATH, StringValueCStr(val));
    } break;
#endif
#if HAVE_CURLOPT_MAX_SEND_SPEED_LARGE
  case CURLOPT_MAX_SEND_SPEED_LARGE: {
    curl_easy_setopt(rbce->curl, CURLOPT_MAX_SEND_SPEED_LARGE, (curl_off_t) NUM2LL(val));
    } break;
#endif
#if HAVE_CURLOPT_MAX_RECV_SPEED_LARGE
  case CURLOPT_MAX_RECV_SPEED_LARGE: {
    curl_easy_setopt(rbce->curl, CURLOPT_MAX_RECV_SPEED_LARGE, (curl_off_t) NUM2LL(val));
    } break;
#endif
#if HAVE_CURLOPT_MAXFILESIZE
  case CURLOPT_MAXFILESIZE:
    curl_easy_setopt(rbce->curl, CURLOPT_MAXFILESIZE, NUM2LONG(val));
    break;
#endif
#if HAVE_CURLOPT_TCP_KEEPALIVE
  case CURLOPT_TCP_KEEPALIVE:
    curl_easy_setopt(rbce->curl, CURLOPT_TCP_KEEPALIVE, NUM2LONG(val));
    break;
  case CURLOPT_TCP_KEEPIDLE:
    curl_easy_setopt(rbce->curl, CURLOPT_TCP_KEEPIDLE, NUM2LONG(val));
    break;
  case CURLOPT_TCP_KEEPINTVL:
    curl_easy_setopt(rbce->curl, CURLOPT_TCP_KEEPINTVL, NUM2LONG(val));
    break;
#endif
#if HAVE_CURLOPT_HAPROXYPROTOCOL
  case CURLOPT_HAPROXYPROTOCOL:
    curl_easy_setopt(rbce->curl, HAVE_CURLOPT_HAPROXYPROTOCOL, NUM2LONG(val));
    break;
#endif
  default:
    rb_raise(rb_eTypeError, "Curb unsupported option");
  }

  return val;
}

#ssl_verify_hostNumeric

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

Returns:

  • (Numeric)


1690
1691
1692
# File 'ext/curb_easy.c', line 1690

static VALUE ruby_curl_easy_ssl_verify_host_get(VALUE self) {
  CURB_IMMED_GETTER(ruby_curl_easy, ssl_verify_host, 0);
}

#ssl_verify_host=(value) ⇒ Object



160
161
162
163
164
# File 'lib/curl/easy.rb', line 160

def ssl_verify_host=(value)
  value = 1 if value.class == TrueClass
  value = 0 if value.class == FalseClass
  self.ssl_verify_host_integer=value
end

#ssl_verify_host?Boolean

call-seq:

easy.ssl_verify_host?                            => boolean

Deprecated: call easy.ssl_verify_host instead can be one of [0,1,2]

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

Returns:

  • (Boolean)


176
177
178
# File 'lib/curl/easy.rb', line 176

def ssl_verify_host?
  ssl_verify_host.nil? ? false : (ssl_verify_host > 0)
end

#ssl_verify_host_integer=(ssl_verify_host) ⇒ Object

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? .



1679
1680
1681
# File 'ext/curb_easy.c', line 1679

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

#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)


1651
1652
1653
# File 'ext/curb_easy.c', line 1651

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)

Returns:

  • (Boolean)


1662
1663
1664
# File 'ext/curb_easy.c', line 1662

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

#ssl_verify_resultInteger

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

Returns:

  • (Integer)


3195
3196
3197
3198
3199
3200
3201
3202
3203
# File 'ext/curb_easy.c', line 3195

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);
}

#ssl_versionFixnum

Get the version of SSL/TLS that libcurl will attempt to use.

Returns:

  • (Fixnum)


1547
1548
1549
# File 'ext/curb_easy.c', line 1547

static VALUE ruby_curl_easy_ssl_version_get(VALUE self, VALUE ssl_version) {
  CURB_IMMED_GETTER(ruby_curl_easy, ssl_version, -1);
}

#ssl_version=(value) ⇒ Fixnum?

Returns:

  • (Fixnum, nil)


1537
1538
1539
# File 'ext/curb_easy.c', line 1537

static VALUE ruby_curl_easy_ssl_version_set(VALUE self, VALUE ssl_version) {
  CURB_IMMED_SETTER(ruby_curl_easy, ssl_version, -1);
}

#start_transfer_timeFloat

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)


2995
2996
2997
2998
2999
3000
3001
3002
3003
# File 'ext/curb_easy.c', line 2995

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);
}

#statusObject

call-seq:

easy.status  => String


22
23
24
25
26
# File 'lib/curl/easy.rb', line 22

def status
  # Matches the last HTTP Status - following the HTTP protocol specification 'Status-Line = HTTP-Version SP Status-Code SP (Opt:)Reason-Phrase CRLF'
  statuses = self.header_str.scan(/HTTP\/\d(\.\d)?\s(\d+\s.*)\r\n/).map{ |match| match[1] }
  statuses.last.strip if statuses.length > 0
end

#sym2curl(opt) ⇒ Object

call-seq:

 easy.sym2curl :symbol => Fixnum

translates ruby symbols to libcurl options


54
55
56
# File 'lib/curl/easy.rb', line 54

def sym2curl(opt)
  Curl.const_get("CURLOPT_#{opt.to_s.upcase}")
end

#timeoutNumeric

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

Uses timeout_ms internally instead of timeout.

Returns:

  • (Numeric)


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

static VALUE ruby_curl_easy_timeout_get(VALUE self) {
  ruby_curl_easy *rbce;
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  return DBL2NUM(rbce->timeout_ms / 1000.0);
}

#timeout=(float) ⇒ Numeric

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).

Uses timeout_ms internally instead of timeout because it allows for better precision and libcurl will use the last set value when both timeout and timeout_ms are set.

Returns:

  • (Numeric)


1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
# File 'ext/curb_easy.c', line 1212

static VALUE ruby_curl_easy_timeout_set(VALUE self, VALUE timeout_s) {
  ruby_curl_easy *rbce;
  Data_Get_Struct(self, ruby_curl_easy, rbce);

  if (Qnil == timeout_s || NUM2DBL(timeout_s) <= 0.0) {
    rbce->timeout_ms = 0;
  } else {
    rbce->timeout_ms = (unsigned long)(NUM2DBL(timeout_s) * 1000);
  }

  return DBL2NUM(rbce->timeout_ms / 1000.0);
}

#timeout_msFixnum?

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

Returns:

  • (Fixnum, nil)


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

static VALUE ruby_curl_easy_timeout_ms_get(VALUE self) {
  ruby_curl_easy *rbce;
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  return LONG2NUM(rbce->timeout_ms);
}

#timeout_ms=(fixnum) ⇒ Fixnum?

Set the maximum time in milliseconds 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)


1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
# File 'ext/curb_easy.c', line 1253

static VALUE ruby_curl_easy_timeout_ms_set(VALUE self, VALUE timeout_ms) {
  ruby_curl_easy *rbce;
  Data_Get_Struct(self, ruby_curl_easy, rbce);

  if (Qnil == timeout_ms || NUM2DBL(timeout_ms) <= 0.0) {
    rbce->timeout_ms = 0;
  } else {
    rbce->timeout_ms = NUM2ULONG(timeout_ms);
  }

  return ULONG2NUM(rbce->timeout_ms);
}

#total_timeFloat

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

Returns:

  • (Float)


2901
2902
2903
2904
2905
2906
2907
2908
2909
# File 'ext/curb_easy.c', line 2901

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%20text") ⇒ 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.



3676
3677
3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
# File 'ext/curb_easy.c', line 3676

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), (int)RSTRING_LEN(str), &rlen);
#else
  result = (char*)curl_unescape(StringValuePtr(str), (int)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)


1777
1778
1779
# File 'ext/curb_easy.c', line 1777

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)

Returns:

  • (Boolean)


1788
1789
1790
# File 'ext/curb_easy.c', line 1788

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

#upload_speedFloat

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

Returns:

  • (Float)


3126
3127
3128
3129
3130
3131
3132
3133
3134
# File 'ext/curb_easy.c', line 3126

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_bytesFloat

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

Returns:

  • (Float)


3092
3093
3094
3095
3096
3097
3098
3099
3100
# File 'ext/curb_easy.c', line 3092

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_lengthFloat

Retrieve the content-length of the upload.

Returns:

  • (Float)


3236
3237
3238
3239
3240
3241
3242
3243
3244
# File 'ext/curb_easy.c', line 3236

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);
}

#urlString

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

Returns:

  • (String)


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

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

#url=(u) ⇒ Object

call-seq:

easy.url = "http://some.url/"                    => "http://some.url/"

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.



127
128
129
# File 'lib/curl/easy.rb', line 127

def url=(u)
  set :url, u
end

#use_netrc=(boolean) ⇒ Boolean

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

Returns:

  • (Boolean)


1724
1725
1726
# File 'ext/curb_easy.c', line 1724

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)

Returns:

  • (Boolean)


1735
1736
1737
# File 'ext/curb_easy.c', line 1735

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

#use_sslFixnum

Get the desired level for using SSL on FTP connections.

Returns:

  • (Fixnum)


1568
1569
1570
# File 'ext/curb_easy.c', line 1568

static VALUE ruby_curl_easy_use_ssl_get(VALUE self, VALUE use_ssl) {
  CURB_IMMED_GETTER(ruby_curl_easy, use_ssl, -1);
}

#use_ssl=(value) ⇒ Fixnum?

Ensure libcurl uses SSL for FTP connections. Valid options are Curl::CURL_USESSL_NONE, Curl::CURL_USESSL_TRY, Curl::CURL_USESSL_CONTROL, and Curl::CURL_USESSL_ALL.

Returns:

  • (Fixnum, nil)


1558
1559
1560
# File 'ext/curb_easy.c', line 1558

static VALUE ruby_curl_easy_use_ssl_set(VALUE self, VALUE use_ssl) {
  CURB_IMMED_SETTER(ruby_curl_easy, use_ssl, -1);
}

#useragent"Ruby/Curb"

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

Returns:

  • ("Ruby/Curb")


782
783
784
# File 'ext/curb_easy.c', line 782

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

#useragent=(useragent) ⇒ Object

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



772
773
774
# File 'ext/curb_easy.c', line 772

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

#usernameString

Get the current username

Returns:

  • (String)


1486
1487
1488
1489
1490
1491
1492
# File 'ext/curb_easy.c', line 1486

static VALUE ruby_curl_easy_username_get(VALUE self, VALUE username) {
#if HAVE_CURLOPT_USERNAME
  CURB_OBJECT_HGETTER(ruby_curl_easy, username);
#else
  return Qnil;
#endif
}

#username=(string) ⇒ String

Set the HTTP Authentication username.

Returns:

  • (String)


1472
1473
1474
1475
1476
1477
1478
# File 'ext/curb_easy.c', line 1472

static VALUE ruby_curl_easy_username_set(VALUE self, VALUE username) {
#if HAVE_CURLOPT_USERNAME
  CURB_OBJECT_HSETTER(ruby_curl_easy, username);
#else
  return Qnil;
#endif
}

#userpwdString

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

Returns:

  • (String)


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

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

#userpwd=(value) ⇒ Object

call-seq:

easy.userpwd = string                            => string

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



198
199
200
# File 'lib/curl/easy.rb', line 198

def userpwd=(value)
  set :userpwd, value
end

#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)


1799
1800
1801
# File 'ext/curb_easy.c', line 1799

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)

Returns:

  • (Boolean)


1810
1811
1812
# File 'ext/curb_easy.c', line 1810

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

#version=(http_version) ⇒ Object

call-seq:

easy = Curl::Easy.new("url")
easy.version = Curl::HTTP_2_0
easy.version = Curl::HTTP_1_1
easy.version = Curl::HTTP_1_0
easy.version = Curl::HTTP_NONE


115
116
117
# File 'lib/curl/easy.rb', line 115

def version=(http_version)
  set :http_version, http_version
end