ethon 0.4.2 → 0.4.3

data/lib/ethon/easy.rb

@@ -1,13 +1,13 @@
-require 'ethon/easies/informations'
-require 'ethon/easies/callbacks'
-require 'ethon/easies/options'
-require 'ethon/easies/header'
-require 'ethon/easies/util'
-require 'ethon/easies/params'
-require 'ethon/easies/form'
-require 'ethon/easies/http'
-require 'ethon/easies/operations'
-require 'ethon/easies/response_callbacks'
+require 'ethon/easy/informations'
+require 'ethon/easy/callbacks'
+require 'ethon/easy/options'
+require 'ethon/easy/header'
+require 'ethon/easy/util'
+require 'ethon/easy/params'
+require 'ethon/easy/form'
+require 'ethon/easy/http'
+require 'ethon/easy/operations'
+require 'ethon/easy/response_callbacks'
 
 module Ethon
 
@@ -32,14 +32,171 @@ module Ethon
   #
   # @see initialize
   class Easy
-    include Ethon::Easies::Informations
-    include Ethon::Easies::Callbacks
-    include Ethon::Easies::Options
-    include Ethon::Easies::Header
-    include Ethon::Easies::Http
-    include Ethon::Easies::Operations
-    include Ethon::Easies::ResponseCallbacks
+    include Ethon::Easy::Informations
+    include Ethon::Easy::Callbacks
+    include Ethon::Easy::Options
+    include Ethon::Easy::Header
+    include Ethon::Easy::Http
+    include Ethon::Easy::Operations
+    include Ethon::Easy::ResponseCallbacks
 
+    # Returns the curl return code.
+    #
+    # @return [ Symbol ] The return code.
+    #   * :ok: All fine. Proceed as usual.
+    #   * :unsupported_protocol: The URL you passed to libcurl used a
+    #     protocol that this libcurl does not support. The support
+    #     might be a compile-time option that you didn't use, it can
+    #     be a misspelled protocol string or just a protocol
+    #     libcurl has no code for.
+    #   * :failed_init: Very early initialization code failed. This
+    #     is likely to be an internal error or problem, or a
+    #     resource problem where something fundamental couldn't
+    #     get done at init time.
+    #   * :url_malformat: The URL was not properly formatted.
+    #   * :not_built_in: A requested feature, protocol or option
+    #     was not found built-in in this libcurl due to a build-time
+    #     decision. This means that a feature or option was not enabled
+    #     or explicitly disabled when libcurl was built and in
+    #     order to get it to function you have to get a rebuilt libcurl.
+    #   * :couldnt_resolve_proxy: Couldn't resolve proxy. The given
+    #     proxy host could not be resolved.
+    #   * :couldnt_resolve_host: Couldn't resolve host. The given remote
+    #     host was not resolved.
+    #   * :couldnt_connect: Failed to connect() to host or proxy.
+    #   * :ftp_weird_server_reply: After connecting to a FTP server,
+    #     libcurl expects to get a certain reply back. This error
+    #     code implies that it got a strange or bad reply. The given
+    #     remote server is probably not an OK FTP server.
+    #   * :remote_access_denied: We were denied access to the resource
+    #     given in the URL. For FTP, this occurs while trying to
+    #     change to the remote directory.
+    #   * :ftp_accept_failed: While waiting for the server to connect
+    #     back when an active FTP session is used, an error code was
+    #     sent over the control connection or similar.
+    #   * :ftp_weird_pass_reply: After having sent the FTP password to
+    #     the server, libcurl expects a proper reply. This error code
+    #     indicates that an unexpected code was returned.
+    #   * :ftp_accept_timeout: During an active FTP session while
+    #     waiting for the server to connect, the CURLOPT_ACCEPTTIMOUT_MS
+    #     (or the internal default) timeout expired.
+    #   * :ftp_weird_pasv_reply: libcurl failed to get a sensible result
+    #     back from the server as a response to either a PASV or a
+    #     EPSV command. The server is flawed.
+    #   * :ftp_weird_227_format: FTP servers return a 227-line as a response
+    #     to a PASV command. If libcurl fails to parse that line,
+    #     this return code is passed back.
+    #   * :ftp_cant_get_host: An internal failure to lookup the host used
+    #     for the new connection.
+    #   * :ftp_couldnt_set_type: Received an error when trying to set
+    #     the transfer mode to binary or ASCII.
+    #   * :partial_file: A file transfer was shorter or larger than
+    #     expected. This happens when the server first reports an expected
+    #     transfer size, and then delivers data that doesn't match the
+    #     previously given size.
+    #   * :ftp_couldnt_retr_file: This was either a weird reply to a
+    #     'RETR' command or a zero byte transfer complete.
+    #   * :quote_error: When sending custom "QUOTE" commands to the
+    #     remote server, one of the commands returned an error code that
+    #     was 400 or higher (for FTP) or otherwise indicated unsuccessful
+    #     completion of the command.
+    #   * :http_returned_error: This is returned if CURLOPT_FAILONERROR is
+    #     set TRUE and the HTTP server returns an error code that is >= 400.
+    #   * :write_error: An error occurred when writing received data to a
+    #     local file, or an error was returned to libcurl from a write callback.
+    #   * :upload_failed: Failed starting the upload. For FTP, the server
+    #     typically denied the STOR command. The error buffer usually
+    #     contains the server's explanation for this.
+    #   * :read_error: There was a problem reading a local file or an error
+    #     returned by the read callback.
+    #   * :out_of_memory: A memory allocation request failed. This is serious
+    #     badness and things are severely screwed up if this ever occurs.
+    #   * :operation_timedout: Operation timeout. The specified time-out
+    #     period was reached according to the conditions.
+    #   * :ftp_port_failed: The FTP PORT command returned error. This mostly
+    #     happens when you haven't specified a good enough address for
+    #     libcurl to use. See CURLOPT_FTPPORT.
+    #   * :ftp_couldnt_use_rest: The FTP REST command returned error. This
+    #     should never happen if the server is sane.
+    #   * :range_error: The server does not support or accept range requests.
+    #   * :http_post_error: This is an odd error that mainly occurs due to
+    #     internal confusion.
+    #   * :ssl_connect_error: A problem occurred somewhere in the SSL/TLS
+    #     handshake. You really want the error buffer and read the message
+    #     there as it pinpoints the problem slightly more. Could be
+    #     certificates (file formats, paths, permissions), passwords, and others.
+    #   * :bad_download_resume: The download could not be resumed because
+    #     the specified offset was out of the file boundary.
+    #   * :file_couldnt_read_file: A file given with FILE:// couldn't be
+    #     opened. Most likely because the file path doesn't identify an
+    #     existing file. Did you check file permissions?
+    #   * :ldap_cannot_bind: LDAP cannot bind. LDAP bind operation failed.
+    #   * :ldap_search_failed: LDAP search failed.
+    #   * :function_not_found: Function not found. A required zlib function was not found.
+    #   * :aborted_by_callback: Aborted by callback. A callback returned
+    #     "abort" to libcurl.
+    #   * :bad_function_argument: Internal error. A function was called with
+    #     a bad parameter.
+    #   * :interface_failed: Interface error. A specified outgoing interface
+    #     could not be used. Set which interface to use for outgoing
+    #     connections' source IP address with CURLOPT_INTERFACE.
+    #   * :too_many_redirects: Too many redirects. When following redirects,
+    #     libcurl hit the maximum amount. Set your limit with CURLOPT_MAXREDIRS.
+    #   * :unknown_option: An option passed to libcurl is not recognized/known.
+    #     Refer to the appropriate documentation. This is most likely a
+    #     problem in the program that uses libcurl. The error buffer might
+    #     contain more specific information about which exact option it concerns.
+    #   * :telnet_option_syntax: A telnet option string was Illegally formatted.
+    #   * :peer_failed_verification: The remote server's SSL certificate or
+    #     SSH md5 fingerprint was deemed not OK.
+    #   * :got_nothing: Nothing was returned from the server, and under the
+    #     circumstances, getting nothing is considered an error.
+    #   * :ssl_engine_notfound: The specified crypto engine wasn't found.
+    #   * :ssl_engine_setfailed: Failed setting the selected SSL crypto engine as default!
+    #   * :send_error: Failed sending network data.
+    #   * :recv_error: Failure with receiving network data.
+    #   * :ssl_certproblem: problem with the local client certificate.
+    #   * :ssl_cipher: Couldn't use specified cipher.
+    #   * :ssl_cacert: Peer certificate cannot be authenticated with known CA certificates.
+    #   * :bad_content_encoding: Unrecognized transfer encoding.
+    #   * :ldap_invalid_url: Invalid LDAP URL.
+    #   * :filesize_exceeded: Maximum file size exceeded.
+    #   * :use_ssl_failed: Requested FTP SSL level failed.
+    #   * :send_fail_rewind: When doing a send operation curl had to rewind the data to
+    #     retransmit, but the rewinding operation failed.
+    #   * :ssl_engine_initfailed: Initiating the SSL Engine failed.
+    #   * :login_denied: The remote server denied curl to login
+    #   * :tftp_notfound: File not found on TFTP server.
+    #   * :tftp_perm: Permission problem on TFTP server.
+    #   * :remote_disk_full: Out of disk space on the server.
+    #   * :tftp_illegal: Illegal TFTP operation.
+    #   * :tftp_unknownid: Unknown TFTP transfer ID.
+    #   * :remote_file_exists: File already exists and will not be overwritten.
+    #   * :tftp_nosuchuser: This error should never be returned by a properly
+    #     functioning TFTP server.
+    #   * :conv_failed: Character conversion failed.
+    #   * :conv_reqd: Caller must register conversion callbacks.
+    #   * :ssl_cacert_badfile: Problem with reading the SSL CA cert (path? access rights?):
+    #   * :remote_file_not_found: The resource referenced in the URL does not exist.
+    #   * :ssh: An unspecified error occurred during the SSH session.
+    #   * :ssl_shutdown_failed: Failed to shut down the SSL connection.
+    #   * :again: Socket is not ready for send/recv wait till it's ready and try again.
+    #     This return code is only returned from curl_easy_recv(3) and curl_easy_send(3)
+    #   * :ssl_crl_badfile: Failed to load CRL file
+    #   * :ssl_issuer_error: Issuer check failed
+    #   * :ftp_pret_failed: The FTP server does not understand the PRET command at
+    #     all or does not support the given argument. Be careful when
+    #     using CURLOPT_CUSTOMREQUEST, a custom LIST command will be sent with PRET CMD
+    #     before PASV as well.
+    #   * :rtsp_cseq_error: Mismatch of RTSP CSeq numbers.
+    #   * :rtsp_session_error: Mismatch of RTSP Session Identifiers.
+    #   * :ftp_bad_file_list: Unable to parse FTP file list (during FTP wildcard downloading).
+    #   * :chunk_failed: Chunk callback reported error.
+    #   * :obsolete: These error codes will never be returned. They were used in an old
+    #     libcurl version and are currently unused.
+    #
+    #
+    # @see http://curl.haxx.se/libcurl/c/libcurl-errors.html
     attr_accessor :return_code
 
     class << self
@@ -66,82 +223,572 @@ module Ethon
     #
     # @param [ Hash ] options The options to set.
     #
-    # @option options :cainfo [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCAINFO.
-    # @option options :capath [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCAPATH.
-    # @option options :connecttimeout [Integer] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCONNECTTIMEOUT.
-    # @option options :copypostfields [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOPYPOSTFIELDS.
-    # @option options :customrequest [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCUSTOMREQUEST.
-    # @option options :dns_cache_timeout [Integer] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTDNSCACHETIMEOUT.
-    # @option options :followlocation [Boolean] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTFOLLOWLOCATION.
-    # @option options :forbid_reuse [Boolean] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTFORBIDREUSE.
-    # @option options :httpauth [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTHTTPAUTH.
-    # @option options :httpget [Boolean] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTHTTPGET.
-    # @option options :httppost [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTHTTPPOST.
-    # @option options :infilesize [Integer] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTINFILESIZE.
-    # @option options :interface [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTINTERFACE.
-    # @option options :maxredirs [Integer] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTMAXREDIRS.
-    # @option options :nobody [Boolean] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTNOBODY.
-    # @option options :nosignal [Boolean] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTNOSIGNAL.
-    # @option options :postfieldsize [Integer] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTPOSTFIELDSIZE.
-    # @option options :proxy [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTPROXY.
-    # @option options :proxyauth [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTPROXYAUTH.
-    # @option options :proxytype [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTPROXYTYPE.
-    # @option options :proxyport [Integer] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTPROXYPORT.
-    # @option options :put [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTPUT.
-    # @option options :readdata [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTREADDATA.
-    # @option options :readfunction [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTREADFUNCTION.
-    # @option options :ssl_verifyhost [Integer] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTSSLVERIFYHOST.
-    # @option options :ssl_verifypeer [Boolean] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTSSLVERIFYPEER.
-    # @option options :sslcert [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTSSLCERT.
-    # @option options :sslcerttype [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTSSLCERTTYPE.
-    # @option options :sslkey [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTSSLKEY.
-    # @option options :sslkeytype [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTSSLKEYTYPE.
-    # @option options :sslversion [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTSSLVERSION.
-    # @option options :timeout [Integer] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTTIMEOUT.
-    # @option options :upload [Boolean] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTUPLOAD.
-    # @option options :url [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTURL.
-    # @option options :useragent [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTUSERAGENT.
-    # @option options :userpwd [String] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTUSERPWD.
-    # @option options :verbose [Boolean] See
-    #  http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTVERBOSE.
+    # @option options :cainfo [String] Pass a char * to a zero terminated
+    #  string naming a file holding one or more certificates to verify
+    #  the peer with. This makes sense only when used in combination with
+    #  the CURLOPT_SSL_VERIFYPEER option. If CURLOPT_SSL_VERIFYPEER is
+    #  zero, CURLOPT_CAINFO need not even indicate an accessible file.
+    #  This option is by default set to the system path where libcurl's
+    #  cacert bundle is assumed to be stored, as established at build time.
+    #  When built against NSS, this is the directory that the NSS certificate
+    #  database resides in.
+    # @option options :capath [String]
+    #  Pass a char * to a zero terminated string naming a directory holding
+    #  multiple CA certificates to verify the peer with. If libcurl is built
+    #  against OpenSSL, the certificate directory must be prepared using the
+    #  openssl c_rehash utility. This makes sense only when used in
+    #  combination with the CURLOPT_SSL_VERIFYPEER option. If
+    #  CURLOPT_SSL_VERIFYPEER is zero, CURLOPT_CAPATH need not even indicate
+    #  an accessible path. The CURLOPT_CAPATH function apparently does not
+    #  work in Windows due to some limitation in openssl. This option is
+    #  OpenSSL-specific and does nothing if libcurl is built to use GnuTLS.
+    #  NSS-powered libcurl provides the option only for backward
+    #  compatibility.
+    # @option options :connecttimeout [Integer]
+    #  Pass a long. It should contain 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 zero to switch to the default built-in connection timeout
+    #  \- 300 seconds. See also the CURLOPT_TIMEOUT option.
+    #  In unix-like systems, this might cause signals to be used unless
+    #  CURLOPT_NOSIGNAL is set.
+    # @option options :connecttimeout_ms [Integer]
+    #  Like CURLOPT_CONNECTTIMEOUT but takes the number of milliseconds
+    #  instead. If libcurl is built to use the standard system name
+    #  resolver, that portion of the connect will still use full-second
+    #  resolution for timeouts with a minimum timeout allowed of one second.
+    #  (Added in 7.16.2)
+    # @option options :copypostfields [String]
+    #  Pass a char * as parameter, which should be the full data to post in
+    #  a HTTP POST operation. It behaves as the CURLOPT_POSTFIELDS option,
+    #  but the original data are copied by the library, allowing the
+    #  application to overwrite the original data after setting this option.
+    #  Because data are copied, care must be taken when using this option in
+    #  conjunction with CURLOPT_POSTFIELDSIZE or
+    #  CURLOPT_POSTFIELDSIZE_LARGE: If the size has not been set prior to
+    #  CURLOPT_COPYPOSTFIELDS, the data are assumed to be a NUL-terminated
+    #  string; else the stored size informs the library about the data byte
+    #  count to copy. In any case, the size must not be changed after
+    #  CURLOPT_COPYPOSTFIELDS, unless another CURLOPT_POSTFIELDS or
+    #  CURLOPT_COPYPOSTFIELDS option is issued. (Added in 7.17.1)
+    # @option options :customrequest [String]
+    #  Pass a pointer to a zero terminated string as parameter. It can be
+    #  used to specify the request instead of GET or HEAD when performing
+    #  HTTP based requests, instead of LIST and NLST when performing FTP
+    #  directory listings and instead of LIST and RETR when issuing POP3
+    #  based commands. This is particularly useful, for example, for
+    #  performing a HTTP DELETE request or a POP3 DELE command.
+    #  Please don't perform this at will, on HTTP based requests, by making
+    #  sure your server supports the command you are sending first.
+    #  When you change the request method by setting CURLOPT_CUSTOMREQUEST
+    #  to something, you don't actually change how libcurl behaves or acts
+    #  in regards to the particular request method, it will only change the
+    #  actual string sent in the request.
+    #  For example:
+    #  With the HTTP protocol when you tell libcurl to do a HEAD request,
+    #  but then specify a GET though a custom request libcurl will still act
+    #  as if it sent a HEAD. To switch to a proper HEAD use CURLOPT_NOBODY,
+    #  to switch to a proper POST use CURLOPT_POST or CURLOPT_POSTFIELDS and
+    #  to switch to a proper GET use CURLOPT_HTTPGET.
+    #  With the POP3 protocol when you tell libcurl to use a custom request
+    #  it will behave like a LIST or RETR command was sent where it expects
+    #  data to be returned by the server. As such CURLOPT_NOBODY should be
+    #  used when specifying commands such as DELE and NOOP for example.
+    #  Restore to the internal default by setting this to NULL.
+    #  Many people have wrongly used this option to replace the entire
+    #  request with their own, including multiple headers and POST contents.
+    #  While that might work in many cases, it will cause libcurl to send
+    #  invalid requests and it could possibly confuse the remote server
+    #  badly. Use CURLOPT_POST and CURLOPT_POSTFIELDS to set POST data. Use
+    #  CURLOPT_HTTPHEADER to replace or extend the set of headers sent by
+    #  libcurl. Use CURLOPT_HTTP_VERSION to change HTTP version.
+    #  (Support for POP3 added in 7.26.0)
+    # @option options :dns_cache_timeout [Integer]
+    #  Pass a long, this sets the timeout in seconds. Name resolves will be
+    #  kept in memory for this number of seconds. Set to zero to completely
+    #  disable caching, or set to -1 to make the cached entries remain
+    #  forever. By default, libcurl caches this info for 60 seconds.
+    #  The name resolve functions of various libc implementations don't
+    #  re-read name server information unless explicitly told so (for
+    #  example, by calling res_init(3)). This may cause libcurl to keep
+    #  using the older server even if DHCP has updated the server info, and
+    #  this may look like a DNS cache issue to the casual libcurl-app user.
+    # @option options :followlocation [Boolean]
+    #  A parameter set to 1 tells the library to follow any Location: header
+    #  that the server sends as part of a HTTP header.
+    #  This means that the library will re-send the same request on the new
+    #  location and follow new Location: headers all the way until no more
+    #  such headers are returned. CURLOPT_MAXREDIRS can be used to limit the
+    #  number of redirects libcurl will follow.
+    #  Since 7.19.4, libcurl can limit what protocols it will automatically
+    #  follow. The accepted protocols are set with CURLOPT_REDIR_PROTOCOLS
+    #  and it excludes the FILE protocol by default.
+    # @option options :forbid_reuse [Boolean]
+    #  Pass a long. Set to 1 to make the next transfer explicitly close the
+    #  connection when done. Normally, libcurl keeps all connections alive
+    #  when done with one transfer in case a succeeding one follows that can
+    #  re-use them. This option should be used with caution and only if you
+    #  understand what it does. Set to 0 to have libcurl keep the connection
+    #  open for possible later re-use (default behavior).
+    # @option options :httpauth [String]
+    #  Pass a long as parameter, which is set to a bitmask, to tell libcurl
+    #  which authentication method(s) you want it to use. The available bits
+    #  are listed below. If more than one bit is set, libcurl will first
+    #  query the site to see which authentication methods it supports and
+    #  then pick the best one you allow it to use. For some methods, this
+    #  will induce an extra network round-trip. Set the actual name and
+    #  password with the CURLOPT_USERPWD option or with the CURLOPT_USERNAME
+    #  and the CURLOPT_PASSWORD options. (Added in 7.10.6)
+    # @option options :httpget [Boolean]
+    #  Pass a long. If the long is 1, this forces the HTTP request to get
+    #  back to GET. Usable if a POST, HEAD, PUT, or a custom request has
+    #  been used previously using the same curl handle.
+    #  When setting CURLOPT_HTTPGET to 1, it will automatically set
+    #  CURLOPT_NOBODY to 0 (since 7.14.1).
+    # @option options :httppost [String]
+    #  Tells libcurl you want a multipart/formdata HTTP POST to be made and
+    #  you instruct what data to pass on to the server. Pass a pointer to a
+    #  linked list of curl_httppost structs as parameter. The easiest way to
+    #  create such a list, is to use curl_formadd(3) as documented. The data
+    #  in this list must remain intact until you close this curl handle
+    #  again with curl_easy_cleanup(3).
+    #  Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue"
+    #  header. You can disable this header with CURLOPT_HTTPHEADER as usual.
+    #  When setting CURLOPT_HTTPPOST, it will automatically set
+    #  CURLOPT_NOBODY to 0 (since 7.14.1).
+    # @option options :infilesize [Integer]
+    #  When uploading a file to a remote site, this option should be used to
+    #  tell libcurl what the expected size of the infile is. This value
+    #  should be passed as a long. See also CURLOPT_INFILESIZE_LARGE.
+    #  For uploading using SCP, this option or CURLOPT_INFILESIZE_LARGE is
+    #  mandatory.
+    #  When sending emails using SMTP, this command can be used to specify
+    #  the optional SIZE parameter for the MAIL FROM command. (Added in
+    #  7.23.0)
+    #  This option does not limit how much data libcurl will actually send,
+    #  as that is controlled entirely by what the read callback returns.
+    # @option options :interface [String]
+    #  Pass a char * as parameter. This sets the interface name to use as
+    #  outgoing network interface. The name can be an interface name, an IP
+    #  address, or a host name.
+    #  Starting with 7.24.0: If the parameter starts with "if!" then it is
+    #  treated as only as interface name and no attempt will ever be named
+    #  to do treat it as an IP address or to do name resolution on it. If
+    #  the parameter starts with "host!" it is treated as either an IP
+    #  address or a hostname. Hostnames are resolved synchronously. Using
+    #  the if! format is highly recommended when using the multi interfaces
+    #  to avoid allowing the code to block. If "if!" is specified but the
+    #  parameter does not match an existing interface,
+    #  CURLE_INTERFACE_FAILED is returned.
+    # @option options :maxredirs [Integer]
+    #  Pass a long. The set number will be the redirection limit. If that
+    #  many redirections have been followed, the next redirect will cause an
+    #  error (CURLE_TOO_MANY_REDIRECTS). This option only makes sense if the
+    #  CURLOPT_FOLLOWLOCATION is used at the same time. Added in 7.15.1:
+    #  Setting the limit to 0 will make libcurl refuse any redirect. Set it
+    #  to -1 for an infinite number of redirects (which is the default)
+    # @option options :nobody [Boolean]
+    #  A parameter set to 1 tells the library to not include the body-part
+    #  in the output. This is only relevant for protocols that have separate
+    #  header and body parts. On HTTP(S) servers, this will make libcurl do
+    #  a HEAD request.
+    #  To change request to GET, you should use CURLOPT_HTTPGET. Change
+    #  request to POST with CURLOPT_POST etc.
+    # @option options :nosignal [Boolean]
+    #  Pass a long. If it is 1, libcurl will not use any functions that
+    #  install signal handlers or any functions that cause signals to be
+    #  sent to the process. This option is mainly here to allow
+    #  multi-threaded unix applications to still set/use all timeout options
+    #  etc, without risking getting signals. (Added in 7.10)
+    #  If this option is set and libcurl has been built with the standard
+    #  name resolver, timeouts will not occur while the name resolve takes
+    #  place. Consider building libcurl with c-ares support to enable
+    #  asynchronous DNS lookups, which enables nice timeouts for name
+    #  resolves without signals.
+    #  Setting CURLOPT_NOSIGNAL to 1 makes libcurl NOT ask the system to
+    #  ignore SIGPIPE signals, which otherwise are sent by the system when
+    #  trying to send data to a socket which is closed in the other end.
+    #  libcurl makes an effort to never cause such SIGPIPEs to trigger, but
+    #  some operating systems have no way to avoid them and even on those
+    #  that have there are some corner cases when they may still happen,
+    #  contrary to our desire. In addition, using CURLAUTH_NTLM_WB
+    #  authentication could cause a SIGCHLD signal to be raised.
+    # @option options :postfieldsize [Integer]
+    #  If you want to post data to the server without letting libcurl do a
+    #  strlen() to measure the data size, this option must be used. When
+    #  this option is used you can post fully binary data, which otherwise
+    #  is likely to fail. If this size is set to -1, the library will use
+    #  strlen() to get the size.
+    # @option options :proxy [String]
+    #  Set HTTP proxy to use. The parameter should be a char * to a zero
+    #  terminated string holding 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. If not specified,
+    #  libcurl will default to using port 1080 for proxies.
+    #  CURLOPT_PROXYPORT.
+    #  When you tell the library to use a 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 CURLOPT_QUOTE and similar FTP specifics
+    #  that don't work unless you tunnel through the HTTP proxy. Such
+    #  tunneling is activated with CURLOPT_HTTPPROXYTUNNEL.
+    #  libcurl respects the environment variables http_proxy, ftp_proxy,
+    #  all_proxy etc, if any of those are set. The CURLOPT_PROXY option does
+    #  however override any possibly set environment variables.
+    #  Setting the proxy string to "" (an empty string) will explicitly
+    #  disable the use of a proxy, even if there is an environment variable
+    #  set for it.
+    #  Since 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
+    #  CURLOPT_PROXY, include protocol prefix (http://) and embedded user +
+    #  password.
+    #  Since 7.21.7, the proxy string may be specified with a protocol://
+    #  prefix to specify alternative proxy protocols. Use socks4://,
+    #  socks4a://, socks5:// or socks5h:// (the last one to enable socks5
+    #  and asking the proxy to do the resolving, also known as
+    #  CURLPROXY_SOCKS5_HOSTNAME type) to request the specific SOCKS version
+    #  to be used. No protocol specified, http:// and all others will be
+    #  treated as HTTP proxies.
+    # @option options :proxyauth [String]
+    #  Pass a long as parameter, which is set to a bitmask, to tell libcurl
+    #  which authentication method(s) you want it to use for your proxy
+    #  authentication. If more than one bit is set, libcurl will first query
+    #  the site to see what authentication methods it supports and then pick
+    #  the best one you allow it to use. For some methods, this will induce
+    #  an extra network round-trip. Set the actual name and password with
+    #  the CURLOPT_PROXYUSERPWD option. The bitmask can be constructed by
+    #  or'ing together the bits listed above for the CURLOPT_HTTPAUTH
+    #  option. As of this writing, only Basic, Digest and NTLM work. (Added
+    #  in 7.10.7)
+    # @option options :proxytype [String]
+    #  Pass a long with this option to set type of the proxy. Available
+    #  options for this are CURLPROXY_HTTP, CURLPROXY_HTTP_1_0 (added in
+    #  7.19.4), CURLPROXY_SOCKS4 (added in 7.10), CURLPROXY_SOCKS5,
+    #  CURLPROXY_SOCKS4A (added in 7.18.0) and CURLPROXY_SOCKS5_HOSTNAME
+    #  (added in 7.18.0). The HTTP type is default. (Added in 7.10)
+    #  If you set CURLOPT_PROXYTYPE to CURLPROXY_HTTP_1_0, it will only
+    #  affect how libcurl speaks to a proxy when CONNECT is used. The HTTP
+    #  version used for "regular" HTTP requests is instead controlled with
+    #  CURLOPT_HTTP_VERSION.
+    # @option options :proxyport [Integer]
+    #  Pass a long with this option to set the proxy port to connect to
+    #  unless it is specified in the proxy string CURLOPT_PROXY.
+    # @option options :readdata [String]
+    #  Data pointer to pass to the file read function. If you use the
+    #  CURLOPT_READFUNCTION option, this is the pointer you'll get as input.
+    #  If you don't specify a read callback but instead rely on the default
+    #  internal read function, this data must be a valid readable FILE *.
+    #  If you're using libcurl as a win32 DLL, you MUST use a
+    #  CURLOPT_READFUNCTION if you set this option.
+    #  This option was also known by the older name CURLOPT_INFILE,
+    #  the name CURLOPT_READDATA was introduced in 7.9.7.
+    # @option options :readfunction [String]
+    #  Pass a pointer to a function that matches the following prototype:
+    #  size_t function( void *ptr, size_t size, size_t nmemb, void
+    #  *userdata); This function gets called by libcurl as soon as it needs
+    #  to read data in order to send it to the peer. The data area pointed
+    #  at by the pointer ptr may be filled with at most size multiplied with
+    #  nmemb number of bytes. Your function must return the actual number of
+    #  bytes that you stored in that memory area. Returning 0 will signal
+    #  end-of-file to the library and cause it to stop the current transfer.
+    #  If you stop the current transfer by returning 0 "pre-maturely" (i.e
+    #  before the server expected it, like when you've said you will upload
+    #  N bytes and you upload less than N bytes), you may experience that
+    #  the server "hangs" waiting for the rest of the data that won't come.
+    #  The read callback may return CURL_READFUNC_ABORT to stop the current
+    #  operation immediately, resulting in a CURLE_ABORTED_BY_CALLBACK error
+    #  code from the transfer (Added in 7.12.1)
+    #  From 7.18.0, the function can return CURL_READFUNC_PAUSE which then
+    #  will cause reading from this connection to become paused. See
+    #  curl_easy_pause(3) for further details.
+    #  Bugs: when doing TFTP uploads, you must return the exact amount of
+    #  data that the callback wants, or it will be considered the final
+    #  packet by the server end and the transfer will end there.
+    #  If you set this callback pointer to NULL, or don't set it at all, the
+    #  default internal read function will be used. It is doing an fread()
+    #  on the FILE * userdata set with CURLOPT_READDATA.
+    # @option options :ssl_verifyhost [Integer]
+    #  Pass a long as parameter.
+    #  This option determines whether libcurl verifies that the server cert
+    #  is for the server it is known as.
+    #  When negotiating a SSL connection, the server sends a certificate
+    #  indicating its identity.
+    #  When CURLOPT_SSL_VERIFYHOST is 2, that certificate must indicate that
+    #  the server is the server to which you meant to connect, or the
+    #  connection fails.
+    #  Curl considers the server the intended one when the Common Name field
+    #  or a Subject Alternate Name field in the certificate matches the host
+    #  name in the URL to which you told Curl to connect.
+    #  When the value is 1, the certificate must contain a Common Name
+    #  field, but it doesn't matter what name it says. (This is not
+    #  ordinarily a useful setting).
+    #  When the value is 0, the connection succeeds regardless of the names
+    #  in the certificate.
+    #  The default value for this option is 2.
+    #  This option controls checking the server's certificate's claimed
+    #  identity. The server could be lying. To control lying, see
+    #  CURLOPT_SSL_VERIFYPEER. If libcurl is built against NSS and
+    #  CURLOPT_SSL_VERIFYPEER is zero, CURLOPT_SSL_VERIFYHOST is ignored.
+    # @option options :ssl_verifypeer [Boolean]
+    #  Pass a long as parameter. By default, curl assumes a value of 1.
+    #  This option determines whether curl verifies the authenticity of the
+    #  peer's certificate. A value of 1 means curl verifies; 0 (zero) means
+    #  it doesn't.
+    #  When negotiating a SSL connection, the server sends a certificate
+    #  indicating its identity. Curl verifies whether the certificate is
+    #  authentic, i.e. that you can trust that the server is who the
+    #  certificate says it is. This trust is based on a chain of digital
+    #  signatures, rooted in certification authority (CA) certificates you
+    #  supply. curl uses a default bundle of CA certificates (the path for
+    #  that is determined at build time) and you can specify alternate
+    #  certificates with the CURLOPT_CAINFO option or the CURLOPT_CAPATH
+    #  option.
+    #  When CURLOPT_SSL_VERIFYPEER is nonzero, and the verification fails to
+    #  prove that the certificate is authentic, the connection fails. When
+    #  the option is zero, the peer certificate verification 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. Use
+    #  CURLOPT_SSL_VERIFYHOST to control that. The check that the host name
+    #  in the certificate is valid for the host name you're connecting to is
+    #  done independently of the CURLOPT_SSL_VERIFYPEER option.
+    # @option options :sslcert [String]
+    #  Pass a pointer to a zero terminated string as parameter. The string
+    #  should be the file name of your certificate. The default format is
+    #  "PEM" and can be changed with CURLOPT_SSLCERTTYPE.
+    #  With NSS this can also be the nickname of the certificate you wish to
+    #  authenticate with. If you want to use a file from the current
+    #  directory, please precede it with "./" prefix, in order to avoid
+    #  confusion with a nickname.
+    # @option options :sslcerttype [String]
+    #  Pass a pointer to a zero terminated string as parameter. The string
+    #  should be the format of your certificate. Supported formats are "PEM"
+    #  and "DER". (Added in 7.9.3)
+    # @option options :sslkey [String]
+    #  Pass a pointer to a zero terminated string as parameter. The string
+    #  should be the file name of your private key. The default format is
+    #  "PEM" and can be changed with CURLOPT_SSLKEYTYPE.
+    # @option options :sslkeytype [String]
+    #  Pass a pointer to a zero terminated string as parameter. The string
+    #  should be the format of your private key. Supported formats are
+    #  "PEM", "DER" and "ENG".
+    #  The format "ENG" enables you to load the private key from a crypto
+    #  engine. In this case CURLOPT_SSLKEY is used as an identifier passed
+    #  to the engine. You have to set the crypto engine with
+    #  CURLOPT_SSLENGINE. "DER" format key file currently does not work
+    #  because of a bug in OpenSSL.
+    # @option options :sslversion [String]
+    #  Pass a long as parameter to control what version of SSL/TLS to
+    #  attempt to use. The available options are:
+    # @option options :timeout [Integer]
+    #  Pass a long as parameter containing 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. This
+    #  option will cause curl to use the SIGALRM to enable time-outing
+    #  system calls.
+    #  In unix-like systems, this might cause signals to be used unless
+    #  CURLOPT_NOSIGNAL is set.
+    #  Default timeout is 0 (zero) which means it never times out.
+    # @option options :timeout_ms [Integer]
+    #  Like CURLOPT_TIMEOUT but takes number of milliseconds instead. If
+    #  libcurl is built to use the standard system name resolver, that
+    #  portion of the transfer will still use full-second resolution for
+    #  timeouts with a minimum timeout allowed of one second. (Added in
+    #  7.16.2)
+    # @option options :upload [Boolean]
+    #  A parameter set to 1 tells the library to prepare for an upload. The
+    #  CURLOPT_READDATA and CURLOPT_INFILESIZE or CURLOPT_INFILESIZE_LARGE
+    #  options are also interesting for uploads. If the protocol is HTTP,
+    #  uploading means using the PUT request unless you tell libcurl
+    #  otherwise.
+    #  Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue"
+    #  header. You can disable this header with CURLOPT_HTTPHEADER as usual.
+    #  If you use PUT to a HTTP 1.1 server, you can upload data without
+    #  knowing the size before starting the transfer if you use chunked
+    #  encoding. You enable this by adding a header like "Transfer-Encoding:
+    #  chunked" with CURLOPT_HTTPHEADER. With HTTP 1.0 or without chunked
+    #  transfer, you must specify the size.
+    # @option options :url [String]
+    #  Pass in a pointer to the actual URL to deal with. The parameter
+    #  should be a char * to a zero terminated string which must be
+    #  URL-encoded in the following format:
+    #  scheme://host:port/path
+    #  For a greater explanation of the format please see RFC 3986.
+    #  If the given URL lacks the scheme, or protocol, part ("http://" or
+    #  "ftp://" etc), libcurl will attempt to resolve which protocol to use
+    #  based on the given host mame. If the protocol is not supported,
+    #  libcurl will return (CURLE_UNSUPPORTED_PROTOCOL) when you call
+    #  curl_easy_perform(3) or curl_multi_perform(3). Use
+    #  curl_version_info(3) for detailed information on which protocols are
+    #  supported.
+    #  The host part of the URL contains the address of the server that you
+    #  want to connect to. This can be the fully qualified domain name of
+    #  the server, the local network name of the machine on your network or
+    #  the IP address of the server or machine represented by either an IPv4
+    #  or IPv6 address. For example:
+    #  http://www.example.com/
+    #  http://hostname/
+    #  http://192.168.0.1/
+    #  http://[2001:1890:1112:1::20]/
+    #  It is also possible to specify the user name and password as part of
+    #  the host, for some protocols, when connecting to servers that require
+    #  authentication.
+    #  For example the following types of authentication support this:
+    #  http://user:password@www.example.com
+    #  ftp://user:password@ftp.example.com
+    #  pop3://user:password@mail.example.com
+    #  The port is optional and when not specified libcurl will use the
+    #  default port based on the determined or specified protocol: 80 for
+    #  HTTP, 21 for FTP and 25 for SMTP, etc. The following examples show
+    #  how to specify the port:
+    #  http://www.example.com:8080/ - This will connect to a web server
+    #  using port 8080 rather than 80.
+    #  smtp://mail.example.com:587/ - This will connect to a SMTP server on
+    #  the alternative mail port.
+    #  The path part of the URL is protocol specific and whilst some
+    #  examples are given below this list is not conclusive:
+    #  HTTP
+    #  The path part of a HTTP request specifies the file to retrieve and
+    #  from what directory. If the directory is not specified then the web
+    #  server's root directory is used. If the file is omitted then the
+    #  default document will be retrieved for either the directory specified
+    #  or the root directory. The exact resource returned for each URL is
+    #  entirely dependent on the server's configuration.
+    #  http://www.example.com - This gets the main page from the web server.
+    #  http://www.example.com/index.html - This returns the main page by
+    #  explicitly requesting it.
+    #  http://www.example.com/contactus/ - This returns the default document
+    #  from the contactus directory.
+    #  FTP
+    #  The path part of an FTP request specifies the file to retrieve and
+    #  from what directory. If the file part is omitted then libcurl
+    #  downloads the directory listing for the directory specified. If the
+    #  directory is omitted then the directory listing for the root / home
+    #  directory will be returned.
+    #  ftp://ftp.example.com - This retrieves the directory listing for the
+    #  root directory.
+    #  ftp://ftp.example.com/readme.txt - This downloads the file readme.txt
+    #  from the root directory.
+    #  ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt
+    #  from the libcurl directory.
+    #  ftp://user:password@ftp.example.com/readme.txt - This retrieves the
+    #  readme.txt file from the user's home directory. When a username and
+    #  password is specified, everything that is specified in the path part
+    #  is relative to the user's home directory. To retrieve files from the
+    #  root directory or a directory underneath the root directory then the
+    #  absolute path must be specified by prepending an additional forward
+    #  slash to the beginning of the path.
+    #  ftp://user:password@ftp.example.com//readme.txt - This retrieves the
+    #  readme.txt from the root directory when logging in as a specified
+    #  user.
+    #  SMTP
+    #  The path part of a SMTP request specifies the host name to present
+    #  during communication with the mail server. If the path is omitted
+    #  then libcurl will attempt to resolve the local computer's host name.
+    #  However, this may not return the fully qualified domain name that is
+    #  required by some mail servers and specifying this path allows you to
+    #  set an alternative name, such as your machine's fully qualified
+    #  domain name, which you might have obtained from an external function
+    #  such as gethostname or getaddrinfo.
+    #  smtp://mail.example.com - This connects to the mail server at
+    #  example.com and sends your local computer's host name in the HELO /
+    #  EHLO command.
+    #  smtp://mail.example.com/client.example.com - This will send
+    #  client.example.com in the HELO / EHLO command to the mail server at
+    #  example.com.
+    #  POP3
+    #  The path part of a POP3 request specifies the mailbox (message) to
+    #  retrieve. If the mailbox is not specified then a list of waiting
+    #  messages is returned instead.
+    #  pop3://user:password@mail.example.com - This lists the available
+    #  messages pop3://user:password@mail.example.com/1 - This retrieves the
+    #  first message
+    #  SCP
+    #  The path part of a SCP request specifies the file to retrieve and
+    #  from what directory. The file part may not be omitted. The file is
+    #  taken as an absolute path from the root directory on the server. To
+    #  specify a path relative to the user's home directory on the server,
+    #  prepend ~/ to the path portion. If the user name is not embedded in
+    #  the URL, it can be set with the CURLOPT_USERPWD or CURLOPT_USERNAME
+    #  option.
+    #  scp://user@example.com/etc/issue - This specifies the file /etc/issue
+    #  scp://example.com/~/my-file - This specifies the file my-file in the
+    #  user's home directory on the server
+    #  SFTP
+    #  The path part of a SFTP request specifies the file to retrieve and
+    #  from what directory. If the file part is omitted then libcurl
+    #  downloads the directory listing for the directory specified. If the
+    #  path ends in a / then a directory listing is returned instead of a
+    #  file. If the path is omitted entirely then the directory listing for
+    #  the root / home directory will be returned. If the user name is not
+    #  embedded in the URL, it can be set with the CURLOPT_USERPWD or
+    #  CURLOPT_USERNAME option.
+    #  sftp://user:password@example.com/etc/issue - This specifies the file
+    #  /etc/issue
+    #  sftp://user@example.com/~/my-file - This specifies the file my-file
+    #  in the user's home directory
+    #  sftp://ssh.example.com/~/Documents/ - This requests a directory
+    #  listing of the Documents directory under the user's home directory
+    #  LDAP
+    #  The path part of a LDAP request can be used to specify the:
+    #  Distinguished Name, Attributes, Scope, Filter and Extension for a
+    #  LDAP search. Each field is separated by a question mark and when that
+    #  field is not required an empty string with the question mark
+    #  separator should be included.
+    #  ldap://ldap.example.com/o=My%20Organisation - This will perform a
+    #  LDAP search with the DN as My Organisation.
+    #  ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will
+    #  perform the same search but will only return postalAddress attributes.
+    #  ldap://ldap.example.com/?rootDomainNamingContext - This specifies an
+    #  empty DN and requests information about the rootDomainNamingContext
+    #  attribute for an Active Directory server.
+    #  For more information about the individual components of a LDAP URL
+    #  please see RFC 4516.
+    #  NOTES
+    #  Starting with version 7.20.0, the fragment part of the URI will not
+    #  be sent as part of the path, which was previously the case.
+    #  CURLOPT_URL is the only option that must be set before
+    #  curl_easy_perform(3) is called.
+    #  CURLOPT_PROTOCOLS can be used to limit what protocols libcurl will
+    #  use for this transfer, independent of what libcurl has been compiled
+    #  to support. That may be useful if you accept the URL from an external
+    #  source and want to limit the accessibility.
+    # @option options :useragent [String]
+    #  Pass a pointer to a zero terminated string as parameter. It will be
+    #  used to set the User-Agent: header in the http request sent to the
+    #  remote server. This can be used to fool servers or scripts. You can
+    #  also set any custom header with CURLOPT_HTTPHEADER.
+    # @option options :userpwd [String]
+    #  Pass a char * as parameter, which should be [user name]:[password] to
+    #  use for the connection. Use CURLOPT_HTTPAUTH to decide the
+    #  authentication method.
+    #  When using NTLM, you can set the domain by prepending it to the user
+    #  name and separating the domain and name with a forward (/) or
+    #  backward slash (\). Like this: "domain/user:password" or
+    #  "domain\user:password". Some HTTP servers (on Windows) support this
+    #  style even for Basic authentication.
+    #  When using HTTP and CURLOPT_FOLLOWLOCATION, libcurl might perform
+    #  several requests to possibly different hosts. libcurl will only send
+    #  this user and password information to hosts using the initial host
+    #  name (unless CURLOPT_UNRESTRICTED_AUTH is set), so if libcurl follows
+    #  locations to other hosts it will not send the user and password to
+    #  those. This is enforced to prevent accidental information leakage.
+    # @option options :verbose [Boolean]
+    #  Set the parameter to 1 to get the library to display a lot of verbose
+    #  information about its operations. Very useful for libcurl and/or
+    #  protocol debugging and understanding. The verbose information will be
+    #  sent to stderr, or the stream set with CURLOPT_STDERR.
+    #  You hardly ever want this set in production use, you will almost
+    #  always want this when you debug/report problems. Another neat option
+    #  for debugging is the CURLOPT_DEBUGFUNCTION.
     #
     # @return [ Easy ] A new Easy.
+    #
+    # @see http://curl.haxx.se/libcurl/c/curl_easy_setopt.html
     def initialize(options = {})
       Curl.init
       ObjectSpace.define_finalizer(self, self.class.finalizer(self))
@@ -179,18 +826,16 @@ module Ethon
       Curl.easy_reset(handle)
     end
 
-    def escape(value)
-      Curl.easy_escape(handle, value, 0)
-    end
-
-    # Returns a  pointer to the curl easy handle.
+    # Url escapes the value.
+    #
+    # @example Url escape.
+    #   easy.escape(value)
     #
-    # @example Return the handle.
-    #   easy.handle
+    # @param [ String ] value The value to escape.
     #
-    # @return [ FFI::Pointer ] A pointer to the curl easy handle.
-    def handle
-      @handle ||= Curl.easy_init
+    # @return [ String ] The escaped value.
+    def escape(value)
+      Curl.easy_escape(handle, value, 0)
     end
 
     # Returns the informations available through libcurl as
@@ -204,7 +849,7 @@ module Ethon
         :response_header => response_header,
         :response_body => response_body
       }
-      Easies::Informations::AVAILABLE_INFORMATIONS.keys.each do |info|
+      Easy::Informations::AVAILABLE_INFORMATIONS.keys.each do |info|
         @hash[info] = method(info).call
       end
       @hash