Class Curl::Easy
In: ext/curb_easy.c
Parent: Object
============= INIT LIB =====================

Methods

autoreferer=   body_str   cacert   cacert=   cert   cert=   cert_key   cert_key=   certpassword=   certtype   certtype=   clone   close   connect_time   connect_timeout   connect_timeout=   content_type   cookiefile   cookiefile=   cookiejar   cookiejar=   cookies   cookies=   delete=   dns_cache_timeout   dns_cache_timeout=   download_speed   downloaded_bytes   downloaded_content_length   dup   enable_cookies=   enable_cookies?   encoding   encoding=   escape   fetch_file_time=   fetch_file_time?   file_time   follow_location=   follow_location?   ftp_commands   ftp_commands=   ftp_entry_path   ftp_filemethod   ftp_filemethod=   ftp_response_timeout   ftp_response_timeout=   head=   header_in_body=   header_in_body?   header_size   header_str   headers   headers=   http   http_auth_types   http_auth_types=   http_connect_code   http_delete   http_delete   http_get   http_get   http_head   http_head   http_post   http_post   http_put   http_put   inspect   interface   interface=   last_effective_url   local_port   local_port=   local_port_range   local_port_range=   max_redirects   max_redirects=   multipart_form_post=   multipart_form_post?   name_lookup_time   new   nosignal=   num_connects   on_body   on_complete   on_debug   on_failure   on_header   on_progress   on_success   os_errno   password   password=   perform   perform   post_body   post_body=   pre_transfer_time   primary_ip   proxy_auth_types   proxy_auth_types=   proxy_port   proxy_port=   proxy_tunnel=   proxy_tunnel?   proxy_type   proxy_type=   proxy_url   proxy_url=   proxypwd   proxypwd=   put_data=   redirect_count   redirect_time   request_size   reset   response_code   ssl_verify_host=   ssl_verify_host?   ssl_verify_peer=   ssl_verify_peer?   ssl_verify_result   ssl_version   ssl_version=   start_transfer_time   timeout   timeout=   total_time   unescape   unrestricted_auth=   unrestricted_auth?   upload_speed   uploaded_bytes   uploaded_content_length   url   url=   use_netrc=   use_netrc?   use_ssl   use_ssl=   useragent   useragent=   username   username=   userpwd   userpwd=   verbose=   verbose?   version=  

Public Class methods

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.

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.

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.

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.

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

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.

Public Instance methods

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

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.

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

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

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

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

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

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

Set a password used to open the specified cert

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

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

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

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.

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

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

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

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.

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

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.

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

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.

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.

call-seq:

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

Obtain the dns cache timeout in seconds.

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.

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

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

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

dup()

Alias for clone

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

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

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

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

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

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

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.

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

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

call-seq

  easy.ftp_commands                                => array or nil

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

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

call-seq

  easy.ftp_filemethod                              => fixnum

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

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

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

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.

call-seq:

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

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

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

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

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.

Obtain the custom HTTP headers for following requests.

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.

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.

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

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.

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

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.

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.

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.

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.

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.

call-seq:

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

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.

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.

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.

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

This option is ignored if compiled against libcurl < 7.15.2.

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.

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.

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.

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

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.

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.

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

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

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

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

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.

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.

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.

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

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.

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.

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

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

Set the HTTP Authentication password.

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

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

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.

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.

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

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

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.

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

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

Configure whether this Curl instance will use proxy tunneling.

Determine whether this Curl instance will use proxy tunneling.

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

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

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

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.

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"

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

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.

Retrieve the total number of redirections that were actually followed.

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

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.

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.

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.

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.

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

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

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.

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

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

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

Sets the version of SSL/TLS that libcurl will attempt to use. Valid options are Curl::CURL_SSLVERSION_TLSv1, Curl::CURL_SSLVERSION::SSLv2, Curl::CURL_SSLVERSION_SSLv3 and Curl::CURL_SSLVERSION_DEFAULT

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.

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

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

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

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.

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

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

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

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

Retrieve the content-length of the upload.

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

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.

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

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

Get the desired level for using SSL on FTP connections.

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.

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

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

Set the HTTP Authentication username.

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

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

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

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

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

[Validate]