Class: Curl::Easy

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

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

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

call-seq:

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

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

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

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



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'ext/curb.rb', line 30

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

  return curl
end

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

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

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

Yields:

  • (easy)

Returns:



2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
 
# File 'ext/curb_easy.c', line 2361

static VALUE ruby_curl_easy_class_perform_delete(int argc, VALUE *argv, VALUE klass) {
  VALUE c = ruby_curl_easy_new(argc, argv, klass);  
  
  if (rb_block_given_p()) {
    rb_yield(c);
  }
  
  ruby_curl_easy_perform_delete(c);
  return c;
}

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

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

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

Yields:

  • (easy)

Returns:



2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
 
# File 'ext/curb_easy.c', line 2340

static VALUE ruby_curl_easy_class_perform_get(int argc, VALUE *argv, VALUE klass) {
  VALUE c = ruby_curl_easy_new(argc, argv, klass);  
  
  if (rb_block_given_p()) {
    rb_yield(c);
  }
  
  ruby_curl_easy_perform_get(c);
  return c;  
}

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

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

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

Overloads:

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

    Returns:

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

    Returns:

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

    Returns:

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

    Returns:

    • (true) 


2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
 
# File 'ext/curb_easy.c', line 2388

static VALUE ruby_curl_easy_class_perform_post(int argc, VALUE *argv, VALUE klass) {   
  VALUE url, fields;
  
  rb_scan_args(argc, argv, "1*", &url, &fields);
  
  VALUE c = ruby_curl_easy_new(1, &url, klass);  
  
  if (argc > 1) {
    ruby_curl_easy_perform_post(argc - 1, &argv[1], c);
  } else {
    ruby_curl_easy_perform_post(0, NULL, c);
  }    
  
  return c;  
}

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

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

Overloads:



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'ext/curb_easy.c', line 128

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

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

  ruby_curl_easy *rbce = ALLOC(ruby_curl_easy);
  
  /* handler */  
  rbce->curl = curl_easy_init();  
  
  /* assoc objects */
  rbce->url = url;
  rbce->proxy_url = Qnil;
  rbce->body_data = Qnil;
  rbce->body_proc = Qnil;
  rbce->header_data = Qnil;
  rbce->header_proc = Qnil;
  rbce->progress_proc = Qnil;
  rbce->debug_proc = Qnil;
  rbce->interface = Qnil;
  rbce->userpwd = Qnil;
  rbce->proxypwd = Qnil;
  rbce->headers = rb_hash_new();
  rbce->cookiejar = Qnil;
  rbce->cert = Qnil;
  rbce->encoding = Qnil;
  rbce->success_proc = Qnil;
  rbce->failure_proc = Qnil;
  rbce->complete_proc = Qnil;
  
  /* various-typed opts */
  rbce->local_port = 0;
  rbce->local_port_range = 0;
  rbce->proxy_port = 0;      
  rbce->proxy_type = -1; 
  rbce->http_auth_types = 0;
  rbce->proxy_auth_types = 0; 
  rbce->max_redirs = -1; 
  rbce->timeout = 0;
  rbce->connect_timeout = 0;
  rbce->dns_cache_timeout = 60;
  rbce->ftp_response_timeout = 0;

  /* bool opts */
  rbce->proxy_tunnel = 0;
  rbce->fetch_file_time = 0;
  rbce->ssl_verify_peer = 1;
  rbce->ssl_verify_host = 1;
  rbce->header_in_body = 0;
  rbce->use_netrc = 0;
  rbce->follow_location = 0;
  rbce->unrestricted_auth = 0;
  rbce->verbose = 0;
  rbce->multipart_form_post = 0;
  rbce->enable_cookies = 0;
  
  /* buffers */
  rbce->postdata_buffer = Qnil;
  rbce->bodybuf = Qnil;
  rbce->headerbuf = Qnil;
  rbce->curl_headers = NULL;
  
  new_curl = Data_Wrap_Struct(cCurlEasy, curl_easy_mark, curl_easy_free, rbce);
  
  if (blk != Qnil) {
    rb_funcall(blk, idCall, 1, new_curl);
  }

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

  return new_curl;  
}

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

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

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

Yields:

  • (easy)

Returns:



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

static VALUE ruby_curl_easy_class_perform(int argc, VALUE *argv, VALUE klass) {
  VALUE c = ruby_curl_easy_new(argc, argv, klass);  
  
  if (rb_block_given_p()) {
    rb_yield(c);
  }
  
  ruby_curl_easy_perform(c);
  return c;  
}

Instance Method Details

#body_str ⇒ Object

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



1696
1697
1698
 
# File 'ext/curb_easy.c', line 1696

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

#cert ⇒ Object

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



438
439
440
 
# File 'ext/curb_easy.c', line 438

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

#cert=(cert) ⇒ Object

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



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

static VALUE ruby_curl_easy_cert_set(VALUE self, VALUE cert) {
  CURB_OBJECT_SETTER(ruby_curl_easy, cert);
}

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

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



215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'ext/curb_easy.c', line 215

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

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  
  newrbce = ALLOC(ruby_curl_easy);
  memcpy(newrbce, rbce, sizeof(ruby_curl_easy));  
  newrbce->curl = curl_easy_duphandle(rbce->curl);
  newrbce->curl_headers = NULL;
  
  return Data_Wrap_Struct(cCurlEasy, curl_easy_mark, curl_easy_free, newrbce);
}

#connect_time ⇒ Float

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

Returns:

  • (Float) 


1850
1851
1852
1853
1854
1855
1856
1857
1858
 
# File 'ext/curb_easy.c', line 1850

static VALUE ruby_curl_easy_connect_time_get(VALUE self) {
  ruby_curl_easy *rbce;
  double time;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_CONNECT_TIME, &time);
  
  return rb_float_new(time);  
}

#connect_timeout ⇒ Fixnum?

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

Returns:

  • (Fixnum, nil) 


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

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) 


674
675
676
 
# File 'ext/curb_easy.c', line 674

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

#content_type ⇒ nil

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

Returns:

  • (nil) 


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

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

#cookiejar ⇒ Object

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



416
417
418
 
# File 'ext/curb_easy.c', line 416

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

#cookiejar=(cookiejar) ⇒ Object

Set a cookiejar file to use for this Curl::Easy instance. This file will be used to persist cookies.

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



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

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

#dns_cache_timeout ⇒ Fixnum?

Obtain the dns cache timeout in seconds.

Returns:

  • (Fixnum, nil) 


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

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) 


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

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

#download_speed ⇒ Float

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

Returns:

  • (Float) 


2005
2006
2007
2008
2009
2010
2011
2012
2013
 
# File 'ext/curb_easy.c', line 2005

static VALUE ruby_curl_easy_download_speed_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_SPEED_DOWNLOAD, &bytes);
  
  return rb_float_new(bytes);  
}

#downloaded_bytes ⇒ Float

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

Returns:

  • (Float) 


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

static VALUE ruby_curl_easy_downloaded_bytes_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_SIZE_DOWNLOAD, &bytes);
  
  return rb_float_new(bytes);  
}

#downloaded_content_length ⇒ Float

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

Returns:

  • (Float) 


2079
2080
2081
2082
2083
2084
2085
2086
2087
 
# File 'ext/curb_easy.c', line 2079

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) 


988
989
990
991
 
# File 'ext/curb_easy.c', line 988

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) 


1000
1001
1002
 
# File 'ext/curb_easy.c', line 1000

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

#encoding ⇒ Object

Get the set encoding types



459
460
461
 
# File 'ext/curb_easy.c', line 459

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

#encoding= ⇒ Object

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



449
450
451
 
# File 'ext/curb_easy.c', line 449

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

#escape("some text") ⇒ Object

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



2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
 
# File 'ext/curb_easy.c', line 2257

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

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

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

#fetch_file_time=(boolean) ⇒ Boolean

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

Returns:

  • (Boolean) 


768
769
770
 
# File 'ext/curb_easy.c', line 768

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) 


779
780
781
 
# File 'ext/curb_easy.c', line 779

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

#file_time ⇒ Fixnum

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

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

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

Returns:

  • (Fixnum) 


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

static VALUE ruby_curl_easy_file_time_get(VALUE self) {
#ifdef HAVE_CURLINFO_FILETIME
  ruby_curl_easy *rbce;
  long time;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_FILETIME, &time);
  
  return LONG2NUM(time);
#else
  rb_warn("Installed libcurl is too old to support file_time");
  return INT2FIX(0);  
#endif
}

#follow_location=(boolean) ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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

#follow_location? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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

#content_type ⇒ nil

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

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

Returns:

  • (nil) 


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

static VALUE ruby_curl_easy_ftp_entry_path_get(VALUE self) {
#ifdef HAVE_CURLINFO_FTP_ENTRY_PATH
  ruby_curl_easy *rbce;
  char* path = NULL;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_FTP_ENTRY_PATH, &path);
  
  if (path && path[0]) {    // curl returns NULL or empty string if none
    return rb_str_new2(path);
  } else {
    return Qnil;
  }
#else
  rb_warn("Installed libcurl is too old to support num_connects");
  return Qnil;
#endif
}

#ftp_response_timeout ⇒ Fixnum?

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

Returns:

  • (Fixnum, nil) 


735
736
737
 
# File 'ext/curb_easy.c', line 735

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) 


725
726
727
 
# File 'ext/curb_easy.c', line 725

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

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


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

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

#header_in_body? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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

#header_size ⇒ Fixnum

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

Returns:

  • (Fixnum) 


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

static VALUE ruby_curl_easy_header_size_get(VALUE self) {
  ruby_curl_easy *rbce;
  long size;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_HEADER_SIZE, &size);
  
  return LONG2NUM(size);  
}

#header_str ⇒ Object

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



1708
1709
1710
 
# File 'ext/curb_easy.c', line 1708

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

#headers ⇒ Hash, ...

Obtain the custom HTTP headers for following requests.

Returns:

  • (Hash, Array, Str) 


324
325
326
 
# File 'ext/curb_easy.c', line 324

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

#headers=(headers) ⇒ Object

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

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

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

For example to set a standard or custom header:

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

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

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

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



314
315
316
 
# File 'ext/curb_easy.c', line 314

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

#http_auth_types ⇒ Fixnum?

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

Returns:

  • (Fixnum, nil) 


583
584
585
 
# File 'ext/curb_easy.c', line 583

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

#http_auth_types=(fixnum) ⇒ Fixnum?

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

Returns:

  • (Fixnum, nil) 


572
573
574
 
# File 'ext/curb_easy.c', line 572

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

#http_connect_code ⇒ Fixnum

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

Returns:

  • (Fixnum) 


1767
1768
1769
1770
1771
1772
1773
1774
1775
 
# File 'ext/curb_easy.c', line 1767

static VALUE ruby_curl_easy_http_connect_code_get(VALUE self) {
  ruby_curl_easy *rbce;
  long code;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_HTTP_CONNECTCODE, &code);
  
  return LONG2NUM(code);  
}

#http_delete ⇒ Object

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



1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
 
# File 'ext/curb_easy.c', line 1554

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

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl = rbce->curl;
  
  curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE");
  // curl_easy_setopt(curl, CURLOPT_NOBODY, 1);

  return handle_perform(self,rbce);
}

#http_get ⇒ true

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

Returns:

  • (true) 


1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
 
# File 'ext/curb_easy.c', line 1534

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

  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl = rbce->curl;
  
  curl_easy_setopt(curl, CURLOPT_HTTPGET, 1);
  
  return handle_perform(self,rbce);
}

#http_head ⇒ true

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

TODO Not yet implemented

Returns:

  • (true) 


1668
1669
1670
 
# File 'ext/curb_easy.c', line 1668

static VALUE ruby_curl_easy_perform_head(VALUE self) {  
  rb_raise(eCurlErrError, "Not yet implemented");
}

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


1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
 
# File 'ext/curb_easy.c', line 1604

static VALUE ruby_curl_easy_perform_post(int argc, VALUE *argv, VALUE self) {  
  ruby_curl_easy *rbce;
  CURL *curl;
  int i;
  VALUE args_ary;
  
  rb_scan_args(argc, argv, "*", &args_ary);
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  curl = curl_easy_duphandle(rbce->curl);
  curl_easy_cleanup(rbce->curl);
  rbce->curl = curl;
  
  if (rbce->multipart_form_post) {
    VALUE ret;
    struct curl_httppost *first = NULL, *last = NULL;

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

    curl_easy_setopt(curl, CURLOPT_POST, 0);
    curl_easy_setopt(curl, CURLOPT_HTTPPOST, first);      
    ret = handle_perform(self,rbce);    
    curl_formfree(first);
    
    return ret;    
  } else {
    long len;
    char *data;
    
    if ((rbce->postdata_buffer = rb_funcall(args_ary, idJoin, 1, rbstrAmp)) == Qnil) {
      rb_raise(eCurlErrError, "Failed to join arguments");
      return Qnil;
    } else { 
      data = StringValuePtr(rbce->postdata_buffer);   
      len = RSTRING_LEN(rbce->postdata_buffer);
      
      curl_easy_setopt(curl, CURLOPT_POST, 1);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data);
      curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, len);

      return handle_perform(self,rbce);
    }
  }
}

#http_put(data) ⇒ true

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

TODO Not yet implemented

Returns:

  • (true) 


1682
1683
1684
 
# File 'ext/curb_easy.c', line 1682

static VALUE ruby_curl_easy_perform_put(VALUE self) {  
  rb_raise(eCurlErrError, "Not yet implemented");
}

#interface ⇒ Object

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



346
347
348
 
# File 'ext/curb_easy.c', line 346

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

#interface=(interface) ⇒ Object

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



335
336
337
 
# File 'ext/curb_easy.c', line 335

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

#last_effective_url ⇒ nil

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

Returns:

  • (nil) 


1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
 
# File 'ext/curb_easy.c', line 1723

static VALUE ruby_curl_easy_last_effective_url_get(VALUE self) {
  ruby_curl_easy *rbce;
  char* url;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_EFFECTIVE_URL, &url);
  
  if (url && url[0]) {    // curl returns empty string if none
    return rb_str_new2(url);
  } else {
    return Qnil;
  }
}

#local_port ⇒ Fixnum?

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

This option is ignored if compiled against libcurl < 7.15.2.

Returns:

  • (Fixnum, nil) 


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

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) 


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

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

#local_port_range ⇒ Fixnum?

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

This option is ignored if compiled against libcurl < 7.15.2.

Returns:

  • (Fixnum, nil) 


519
520
521
 
# File 'ext/curb_easy.c', line 519

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) 


506
507
508
 
# File 'ext/curb_easy.c', line 506

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

#max_redirects ⇒ Fixnum?

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

Returns:

  • (Fixnum, nil) 


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

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) 


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

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

#multipart_form_post=(boolean) ⇒ Boolean

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

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

Returns:

  • (Boolean) 


965
966
967
968
 
# File 'ext/curb_easy.c', line 965

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) 


977
978
979
 
# File 'ext/curb_easy.c', line 977

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

#name_lookup_time ⇒ Float

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

Returns:

  • (Float) 


1833
1834
1835
1836
1837
1838
1839
1840
1841
 
# File 'ext/curb_easy.c', line 1833

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

#num_connects ⇒ Integer

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

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

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

Returns:

  • (Integer) 


2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
 
# File 'ext/curb_easy.c', line 2185

static VALUE ruby_curl_easy_num_connects_get(VALUE self) {
#ifdef HAVE_CURLINFO_NUM_CONNECTS
  ruby_curl_easy *rbce;
  long result;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_NUM_CONNECTS, &result);
  
  return LONG2NUM(result);  
#else
  rb_warn("Installed libcurl is too old to support num_connects");
  return INT2FIX(-1);
#endif
}

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

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

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

Yields:

  • (body_data) 


1021
1022
1023
 
# File 'ext/curb_easy.c', line 1021

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

#on_complete { ... } ⇒ Object

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

The on_complete handler is called when the request is finished.

Yields:



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

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

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

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

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

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

Yields:

  • (type, data) 


1123
1124
1125
 
# File 'ext/curb_easy.c', line 1123

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

#on_failure { ... } ⇒ Object

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

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

Yields:



1051
1052
1053
 
# File 'ext/curb_easy.c', line 1051

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

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

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

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

Yields:

  • (header_data) 


1081
1082
1083
 
# File 'ext/curb_easy.c', line 1081

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

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

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

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

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

Yields:

  • (dl_total, dl_now, ul_total, ul_now) 


1102
1103
1104
 
# File 'ext/curb_easy.c', line 1102

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

#on_success { ... } ⇒ Object

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

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

Yields:



1036
1037
1038
 
# File 'ext/curb_easy.c', line 1036

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

#os_errno ⇒ Integer

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

Returns:

  • (Integer) 


2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
 
# File 'ext/curb_easy.c', line 2156

static VALUE ruby_curl_easy_os_errno_get(VALUE self) {
#ifdef HAVE_CURLINFO_OS_ERRNO
  ruby_curl_easy *rbce;
  long result;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_OS_ERRNO, &result);
  
  return LONG2NUM(result);  
#else
  rb_warn("Installed libcurl is too old to support os_errno");
  return INT2FIX(0);
#endif
}

#perform ⇒ true

Transfer the currently configured URL using the options set for this Curl::Easy instance. If this is an HTTP URL, it will be transferred via the GET request method (i.e. this method is a synonym for http_get when using HTTP URLs).

Returns:

  • (true) 


1576
1577
1578
 
# File 'ext/curb_easy.c', line 1576

static VALUE ruby_curl_easy_perform(VALUE self) {  
  return ruby_curl_easy_perform_get(self);
}

#pre_transfer_time ⇒ Float

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

Returns:

  • (Float) 


1869
1870
1871
1872
1873
1874
1875
1876
1877
 
# File 'ext/curb_easy.c', line 1869

static VALUE ruby_curl_easy_pre_transfer_time_get(VALUE self) {
  ruby_curl_easy *rbce;
  double time;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_PRETRANSFER_TIME, &time);
  
  return rb_float_new(time);  
}

#proxy_auth_types ⇒ Fixnum?

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

Returns:

  • (Fixnum, nil) 


606
607
608
 
# File 'ext/curb_easy.c', line 606

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) 


595
596
597
 
# File 'ext/curb_easy.c', line 595

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

#proxy_port ⇒ Fixnum?

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

Returns:

  • (Fixnum, nil) 


539
540
541
 
# File 'ext/curb_easy.c', line 539

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) 


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

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) 


747
748
749
 
# File 'ext/curb_easy.c', line 747

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) 


757
758
759
 
# File 'ext/curb_easy.c', line 757

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

#proxy_type ⇒ Fixnum?

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

Returns:

  • (Fixnum, nil) 


560
561
562
 
# File 'ext/curb_easy.c', line 560

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) 


550
551
552
 
# File 'ext/curb_easy.c', line 550

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

#proxy_url ⇒ Object

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



288
289
290
 
# File 'ext/curb_easy.c', line 288

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

#proxy_url=(proxy_url) ⇒ Object

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

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

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

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



278
279
280
 
# File 'ext/curb_easy.c', line 278

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

#proxypwd ⇒ Object

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



392
393
394
 
# File 'ext/curb_easy.c', line 392

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

#proxypwd=(proxypwd) ⇒ Object

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



380
381
382
 
# File 'ext/curb_easy.c', line 380

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

#redirect_count ⇒ Integer

Retrieve the total number of redirections that were actually followed.

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

Returns:

  • (Integer) 


1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
 
# File 'ext/curb_easy.c', line 1931

static VALUE ruby_curl_easy_redirect_count_get(VALUE self) {
#ifdef HAVE_CURLINFO_REDIRECT_COUNT
  ruby_curl_easy *rbce;
  long count;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_REDIRECT_COUNT, &count);
  
  return LONG2NUM(count);
#else
  rb_warn("Installed libcurl is too old to support redirect_count");
  return INT2FIX(-1);
#endif
    
}

#redirect_time ⇒ Float

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

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

Returns:

  • (Float) 


1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
 
# File 'ext/curb_easy.c', line 1908

static VALUE ruby_curl_easy_redirect_time_get(VALUE self) {
#ifdef HAVE_CURLINFO_REDIRECT_TIME
  ruby_curl_easy *rbce;
  double time;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_REDIRECT_TIME, &time);
  
  return rb_float_new(time); 
#else
  rb_warn("Installed libcurl is too old to support redirect_time");
  return rb_float_new(-1);
#endif
}

#request_size ⇒ Fixnum

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

Returns:

  • (Fixnum) 


2040
2041
2042
2043
2044
2045
2046
2047
2048
 
# File 'ext/curb_easy.c', line 2040

static VALUE ruby_curl_easy_request_size_get(VALUE self) {
  ruby_curl_easy *rbce;
  long size;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_REQUEST_SIZE, &size);
  
  return LONG2NUM(size);  
}

#response_code ⇒ Fixnum

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

Returns:

  • (Fixnum) 


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

static VALUE ruby_curl_easy_response_code_get(VALUE self) {
  ruby_curl_easy *rbce;
  long code;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
#ifdef HAVE_CURLINFO_RESPONSE_CODE
  curl_easy_getinfo(rbce->curl, CURLINFO_RESPONSE_CODE, &code);
#else
  // old libcurl
  curl_easy_getinfo(rbce->curl, CURLINFO_HTTP_CODE, &code);
#endif
  
  return LONG2NUM(code);  
}

#ssl_verify_host=(boolean) ⇒ Boolean

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

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

Returns:

  • (Boolean) 


825
826
827
 
# File 'ext/curb_easy.c', line 825

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

#ssl_verify_host? ⇒ Boolean

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

Returns:

  • (Boolean) 


836
837
838
 
# File 'ext/curb_easy.c', line 836

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

#ssl_verify_peer=(boolean) ⇒ Boolean

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

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

Returns:

  • (Boolean) 


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

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) 


808
809
810
 
# File 'ext/curb_easy.c', line 808

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

#ssl_verify_result ⇒ Integer

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

Returns:

  • (Integer) 


2057
2058
2059
2060
2061
2062
2063
2064
2065
 
# File 'ext/curb_easy.c', line 2057

static VALUE ruby_curl_easy_ssl_verify_result_get(VALUE self) {
  ruby_curl_easy *rbce;
  long result;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_SSL_VERIFYRESULT, &result);
  
  return LONG2NUM(result);  
}

#start_transfer_time ⇒ Float

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

Returns:

  • (Float) 


1887
1888
1889
1890
1891
1892
1893
1894
1895
 
# File 'ext/curb_easy.c', line 1887

static VALUE ruby_curl_easy_start_transfer_time_get(VALUE self) {
  ruby_curl_easy *rbce;
  double time;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_STARTTRANSFER_TIME, &time);
  
  return rb_float_new(time);  
}

#timeout ⇒ Fixnum?

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

Returns:

  • (Fixnum, nil) 


659
660
661
 
# File 'ext/curb_easy.c', line 659

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

#timeout=(fixnum) ⇒ Fixnum?

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

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

Returns:

  • (Fixnum, nil) 


648
649
650
 
# File 'ext/curb_easy.c', line 648

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

#total_time ⇒ Float

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

Returns:

  • (Float) 


1816
1817
1818
1819
1820
1821
1822
1823
1824
 
# File 'ext/curb_easy.c', line 1816

static VALUE ruby_curl_easy_total_time_get(VALUE self) {
  ruby_curl_easy *rbce;
  double time;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_TOTAL_TIME, &time);
  
  return rb_float_new(time);  
}

#unescape("some text") ⇒ Object

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



2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
 
# File 'ext/curb_easy.c', line 2284

static VALUE ruby_curl_easy_unescape(VALUE self, VALUE str) {
  ruby_curl_easy *rbce;
  int rlen;
  char *result;
  VALUE rresult;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);
  
#if (LIBCURL_VERSION_NUM >= 0x070f04)
  result = (char*)curl_easy_unescape(rbce->curl, StringValuePtr(str), RSTRING_LEN(str), &rlen);
#else
  result = (char*)curl_unescape(StringValuePtr(str), RSTRING_LEN(str));
  rlen = strlen(result);
#endif

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

#unrestricted_auth=(boolean) ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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) 


926
927
928
 
# File 'ext/curb_easy.c', line 926

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

#upload_speed ⇒ Float

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

Returns:

  • (Float) 


1988
1989
1990
1991
1992
1993
1994
1995
1996
 
# File 'ext/curb_easy.c', line 1988

static VALUE ruby_curl_easy_upload_speed_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_SPEED_UPLOAD, &bytes);
  
  return rb_float_new(bytes);  
}

#uploaded_bytes ⇒ Float

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

Returns:

  • (Float) 


1954
1955
1956
1957
1958
1959
1960
1961
1962
 
# File 'ext/curb_easy.c', line 1954

static VALUE ruby_curl_easy_uploaded_bytes_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_SIZE_UPLOAD, &bytes);
  
  return rb_float_new(bytes);  
}

#uploaded_content_length ⇒ Float

Retrieve the content-length of the upload.

Returns:

  • (Float) 


2095
2096
2097
2098
2099
2100
2101
2102
2103
 
# File 'ext/curb_easy.c', line 2095

static VALUE ruby_curl_easy_uploaded_content_length_get(VALUE self) {
  ruby_curl_easy *rbce;
  double bytes;
  
  Data_Get_Struct(self, ruby_curl_easy, rbce);  
  curl_easy_getinfo(rbce->curl, CURLINFO_CONTENT_LENGTH_UPLOAD, &bytes);
  
  return rb_float_new(bytes);  
}

#url ⇒ Object

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



249
250
251
 
# File 'ext/curb_easy.c', line 249

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

#url=(url) ⇒ Object

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



239
240
241
 
# File 'ext/curb_easy.c', line 239

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

#use_netrc=(boolean) ⇒ Boolean

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

Returns:

  • (Boolean) 


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

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) 


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

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

#userpwd ⇒ Object

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



368
369
370
 
# File 'ext/curb_easy.c', line 368

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

#userpwd=(userpwd) ⇒ Object

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



357
358
359
 
# File 'ext/curb_easy.c', line 357

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

#verbose=(boolean) ⇒ Boolean

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

Returns:

  • (Boolean) 


937
938
939
 
# File 'ext/curb_easy.c', line 937

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) 


948
949
950
 
# File 'ext/curb_easy.c', line 948

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