65.5 FFI-bindings for libcurl

The next passages introduce bindings defined on top of the current FFI implementation. To conceal the poorly conceived documentation of FFI itself we strongly advertise to work out the whole power of FFI by these example application.

cURL is a command line tool for transferring files with URL syntax, supporting FTP, FTPS, TFTP, HTTP, HTTPS, GOPHER, TELNET, DICT, FILE and LDAP. cURL supports HTTPS certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate, kerberos, …), file transfer resume, proxy tunneling and a busload of other useful tricks.

The cURL-API is, like cURL itself, free and open software. The main entrance to cURL is the curl-easy interface, which ffi-curl.el intends to implement.

The FFI-bindings for libcurl can be classified roughly into guts and main procedures (there is actually only one main procedure). However, we discuss the guts of the API now.

65.5.1 Low-level functions of ffi-curl.el

As usual, the function’s communication takes place via contextes, hence any of the cURL functions expect a context handle which is initially produced by curl:easy-init.

Function: curl:easy-init

Initialise curl easy interface and return a context handle.

Function: curl:easy-cleanup ctx

Clean up context ctx and free resources allocated with it. This function must be called after every easy session.

Remember to always free all requested context handles. The garbage collector of SXEmacs has no influence on them nor on their allocated memory.

(let ((context (curl:easy-init)))
  (curl:easy-cleanup context))
     ⇒ nil

Having allocated a context handle all cURL functions use it by reference, that is functions change it by side-effect or magically retrieve values from it.

Function: curl:easy-setopt ctx &rest options

Set options for curl transfer in session ctx.

Options are passed as keyword-value-pairs. Supported keywords are:

• :url ‘string’ – a valid Uniform Resource Locator.
• :fstream ‘ffi-fo’ – a file descriptor to which output is redirected.

Function: curl:easy-perform ctx

Perform cURL operation on the context ctx.

To control the behaviour of the session or set options into the context, see curl:easy-setopt.

Function: curl:easy-getinfo ctx what

Get info from the context ctx about what.

Constant: curl:errors-alist

Alist of error codes and associated clear-text error messages.

65.5.2 User-level functions of ffi-curl.el

All of the prior routines have been used to define a user-level function which can be used without the need to deal with the internals.

Function: curl:download url file &rest options

Download the contents url to and write them to file. Return 0 on success or an integer specifying an error code.

Optionally you can specify keywords in options. The options are keyword-value-pairs and are set via curl:easy-setopt.

(curl:download "http://www.sxemacs.org"
  (expand-file-name (make-temp-name "curl") (temp-directory)))
     ⇒ 0