curl
![[Picture of an egg]](egg.jpg)
curl is a tinyclos wrapper for libcurl, a MIT/X-licensed multiprotocol file transfer library. It is designed to integrate well with Scheme input-output ports.
NOTE: this egg is alpha software. Some basic functions work but it is incomplete and may even cause damage by, for instance, overwriting files on your computer.
This documentation is also very incomplete. Some of the documented options have not been tested.
Quick example:
$ csi
> (use curl)
> (define html-output (with-output-to-string
> (lambda () (curl-perform (curl 'easy 'url "http://www.example.com")))))
> html-output
Create a tinyclos object of the type <curl-easy> or <curl-multi>.
The type of curl object to create: 'easy or 'multi
Optional list of symbols and values (as in curl-set-options!)
Set an option of a <curl-easy> object.
A <curl-easy> object
The name of a <curl-easy> option
A value of a type appropriate to the option.
Set a list of options of a <curl-easy> object.
A <curl-easy> object
The name of a <curl-easy> option
A value of a type appropriate to the option.
Returns a string describing the error code.
Symbolic error code returned by a <curl-easy> method.
Execute a file operation specified by a <curl-easy> object.
A <curl-easy> object
Reset a <curl-easy> object to an initial state. All options are set to their default values.
A <curl-easy> object
Unless this value evaluates to #f, any associated curl handle is released.
The curl-set-option! and curl-set-options! methods can set the following options of a <curl-easy> object.
| Option | Type | Description |
|---|---|---|
| 'url | string | target URL for the file transfer |
| 'file | function | also called 'writedata. A thunk returning a port, or some other value of use to what function nominated in 'writefunction |
| 'port | long | remote port to connect to |
| 'proxy | string | HTTP proxy to use (host name or dotted IPV4 address, with optional port number after a colon. |
| 'userpwd | string | username:password for authentication at the target URL (see 'httpauth) |
| 'proxyuserpwd | string | username:password for authentication at the proxy (see 'proxyauth) |
| 'range | string | the character range of the document required |
| 'errorbuffer | string | an error message buffer. |
| 'writefunction | callback | a callback function to be used for writing data. See 'file |
| 'readfunction | callback | a callback function to be used for reading data |
| 'timeout | long | timeout for transfers in seconds |
| 'infilesize | long | expected size of file upload. |
| 'postfields | string | fully encoded fields to be sent in a HTTP POST operation. |
| 'referer | string | custom referer field |
| 'ftpport | string | address of ftp port in active mode |
| 'useragent | string | custom useragent field |
| 'low_speed_limit | long | connection quality threshold. |
| 'low_speed_time | long | connection low quality timeout |
| 'resume_from | long | offset to the number of bytes at which to resume the transfer. Set to -1 to resume an interrupted ftp transfer at the end of the target file. |
| 'cookie | string | a cookie (or cookies) to set during a file transfer |
| 'httpheader | list | list of http headers. |
| 'httppost | list | list http post headers |
| 'sslcert | string | filename of SSL certificate |
| 'sslcertpasswd | string | password required to use the SSL certificate |
| 'sslkeypasswd | string | password required to use the SSL private key |
| 'crlf | long | convert UNIX newlines to CRLF on transfer. |
| 'quote | list | list of ftp commands to pass to server prior to transfer |
| 'cookiefile | string | name of a file holding cookie data to read |
| 'sslversion | long | version of ssl/tls to use |
| 'timecondition | long | how to treat timevalue |
| 'timevalue | long | time used in 'timecondition |
| 'customrequest | string | command to use instead of, for instance, GET or POST |
| 'postquote | list | list of ftp commands to execute after transfer |
| 'writeinfo | string | Undocumented |
| 'verbose | long | set to non-zero to get a lot of diagnostic output on stderr (or the file handle set by 'stderr) |
| 'header | long | set to non-zero to include the header in the body output |
| 'noprogress | long | set to non-zero to shut down the built-in progress meter |
| 'nobody | long | set to non-zero to disable output of the body portion |
| 'failonerror | long | set to non-zero to abort the download on receiving a HTTP reply code of 400 or more |
| 'upload | long | set to non-zero to prepare for an upload |
| 'post | long | set to non-zero to perform a HTTP POST |
| 'ftplistonly | long | set to non-zero to list only filenames in a ftp directory, not sizes, dates and permissions. |
| 'ftpappend | long | set to non-zero to append to a remote file instead of overwriting |
| 'netrc | long | whether and how to use the user's netrc file |
| 'followlocation | long | set to non-zero to ask libcurl to follow Location: headers received during a transfer |
| 'transfertext | long | set to non-zero to use ascii mode for ftp transfers |
| 'put | long | set to non-zero to use HTTP PUT to transfer data |
| 'progressfunction | callback | callback to handle transfer progress reporting |
| 'progressdata | c-pointer | Data to be passed to progressfunction |
| 'autoreferer | long | set to non-zero to automatically set referer: field when following a redirect |
| 'proxyport | long | proxy port to connect to if port is not specified in the proxy string |
| 'postfieldsize | long | size of data field to be transferred |
| 'httpproxytunnel | long | set to non-zero to use tunneling through the proxy |
| 'interface | string | outgoing network interface to be used |
| 'krb4level | string | krb4 security level |
| 'ssl_verifypeer | long | set to non-zero to trigger verification of the peer's SSL certificate |
| 'cainfo | string | set to the name of a file containing a certificate bundle against which to verify certificates. If not set, libcurl's default cacert bundle is used. |
| 'maxredirs | long | set to non-zero value to allow a limited number of redirects. The default is to not allow redirects. Set to -1 to allow indefinite redirects. |
| 'filetime | long | set to non-zero to make libcurl try to get the modification date of the remote document. |
| 'telnetoptions | list | list of variables to send to telnet negotiations. |
| 'maxconnects | long | set to the maximum number of simultaneous open connections libcurl is to cache. If this is not set, the default is 5. |
| 'fresh_connect | long | set to non-zero to make the next transfer use a new connection. |
| 'forbid_reuse | long | set to non-zero to make the next transfer close the connection when done. |
| 'random_file | string | set to the name of a file to be used as a random seed for the SSL engine |
| 'egdsocket | string | set to the path name of the Entropy Gathering Daemon socket, to be used as a random seed for the SSL engine. |
| 'connecttimeout | long | maximum time in seconds to take to establish the connection. |
| 'headerfunction | callback | pointer to a callback to use to write header. |
| 'httpget | long | set to non-zero value after a HTTP POST, to go back to HTTP GET mode. |
| 'ssl_verifyhost | long | set to non-zero to trigger verification that the host is the one certified by the certificate. |
| 'cookiejar | string | set to the name of a file to receive all cookies when the curl is closed. |
| 'ssl_cipher_list | string | a string containing a list of ciphers to use for SSL connection. |
| 'http_version | long | set to '1_0, '1_1, (or '1.0 or '1.1) or 'none (the latter actually means "don't care") |
| 'ftp_use_epsv | long | set to non-zero to force libcurl attempt to use of EPSC for passive transfers (which is the default.) Set to 0 to suppress the default. |
| 'sslcerttype | string | set to the format of the SSL certificate given in 'sslcert. Default is "PEM". |
| 'sslkey | string | filename of SSL private key. |
| 'sslkeytype | string | set to the format of the SSL private key. Default is "PEM". |
| 'sslengine | string | Identifier of the crypto engine to be used for private key. |
| 'sslengine_default | string | Identifier of actual crypto engine to use for assymmetric crypto operations. |
| 'dns_use_global_cache | long | set to non-zero to ask libcurl to use a global DNS cache that will survive between easy handle creations and deletions. This is not thread-safe and this will use a global variable. |
| 'dns_cache_timeout | long | set to number of seconds resolved names are to be kept in cache memory. Setting to 0 disables DNS caching. Default is 60 seconds. |
| 'prequote | list | list of ftp commands to send to the server after the transfer type is set. |
| 'debugfunction | c-function | Callback function to perform debug tracing. |
| 'debugdata | c-pointer | Private data for debug function. |
| 'cookiesession | long | Set to non-zero for force a new cookie session. |
| 'capath | string | path to directory holding CA certificates. OpenSSL-specific and apparently doesn't work on Windows. |
| 'buffersize | long | set to requested buffer size. By default the buffer is set as large as possible (CURL_MAX_WRITE_SIZE in <curl/curl.h>). |
| 'nosignal | long | set to non-zero to suppress use of signals. |
| 'share | <curl-share> | set to share handle. If this is set the underlying CURL object will use the options of the share handle, not those set in this object. |
| 'proxytype | symbol | set to 'http, 'socks4, or 'socks5. Default is 'http |
| 'encoding | string | contents of the HTTP Accept-Encoding header. The three encodings supported are identity, deflate and gzip. By default all three are acceped. |
| 'private | string | private information that can subsequently be retrieved using getinfo. |
| 'http200aliases | list | set to a list of aliases to be treated as valid 200 HTTP responses. |
| 'unrestricted_auth | long | set to non-zero to enable use of username/password when following location headers. |
| 'ftp_use_eprt | long | set to non-zero to tell libcurl to use EPRT (and LPRT) in active ftp downloads. |
| 'httpauth | symbol or list of symbols | set to the authentication methods to use. Values are one or more or 'basic, 'digest, 'gssnegotiate, 'ntlm, 'any. |
| 'ssl_ctx_function | callback | Callback to permit tweaking of SSL connection setup. |
| 'ssl_ctx_data | c-pointer | Data pointer to pass to ssl_ctx_function |
| 'ftp_create_missing_dirs | long | set to non-zero to have ftp attempt to create any directory it cannot cwd into. |
| 'proxyauth | symbol or list of symbols | set to the authentication methods to use. Values are one or more or 'basic, 'digest, 'gssnegotiate, 'ntlm, 'any. |
| 'ftp_response_timeout | long | number of seconds to wait for response to a ftp command before timing out the session. |
| 'ipresolve | symbol | set to one of the following to determine how addresses are to be resolved: 'ipv4, 'ipv6, 'whatever. |
| 'maxfilesize | long | |
| 'infilesize_large | curl-offset | |
| 'resume_from_large | curl-offset | |
| 'maxfilesize_large | curl-offset | |
| 'netrc_file | string | |
| 'ftp_ssl | long | |
| 'postfieldsize_large | curl-offset | |
| 'tcp_nodelay | long | |
| 'source_userpwd | string | |
| 'source_prequote | list | |
| 'source_postquote | list | |
| 'ftpsslauth | long | |
| 'ioctlfunction | c-function | |
| 'ioctldata | c-pointer | |
| 'ftp_account | string | |
| 'cookielist | string | |
| 'ignore_content_length | long | |
| 'ftp_skip_pasv_ip | long | |
| 'ftp_filemethod | long |
ok unsupported-protocol failed-init url-malformat url-malformat-user
couldnt-resolve-proxy couldnt-resolve-host couldnt-connect
ftp-weird-server-reply ftp-access-denied ftp-user-password-incorrect
ftp-weird-pass-reply ftp-weird-user-reply ftp-weird-pasv-reply
ftp-weird-227-format ftp-cant-get-host ftp-cant-reconnect
ftp-couldnt-set-binary partial-file ftp-couldnt-retr-file ftp-write-error
ftp-quote-error httpe-returned-error write-error malformat-user
ftp-couldnt-stor-file read-error out-of-memory operation-timeouted
ftp-couldnt-set-ascii ftp-port-failed ftp-couldnt-use-rest ftp-couldnt-get-size
http-range-error http-post-error ssl-connect-error bad-download-resume
file-couldnt-read-file ldap-cannot-bind ldap-search-failed library-not-found
function-not-found aborted-by-callback bad-function-argument
bad-calling-order interface-failed bad-password-entered too-many-redirects
unknown-telnet-option telnet-option-syntax obsolete ssl-peer-certificate
got-nothing ssl-engine-notfound ssl-engine-setfailed send-error recv-error
share-in-use ssl-certproblem ssl-cipher ssl-cacert bad-content-encoding
ldap-invalid-url filesize-exceeded ftp-ssl-failed send-fail-rewind
ssl-engine-initfailed login-denied tftp-notfound tftp-perm tftp-diskfull
tftp-illegal tftp-unknownid tftp-exists tftp-nosuchuser
Copyright (c) 2007, Tony Sidaway All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.