XEmacs Lisp binding for libcurl
===============================

libcurl is the library API for cURL.  Documentation is available at
http://curl.haxx.se/.

This is primarily a C module, not a Lisp library.  There is a Lisp library
which initializes some data structures and requires the module; this
structure will probably be changed in the future.

The current version of the module exposes the libcurl "easy" interface via
the following Lisp API.  It adds one object type, "URL handle", and the
functions and variables listed below.

The naming scheme will seem a little odd.  My intention is to unify a number
of different URL handling implementations, probably including EFS, TRAMP and
libneon, under the url-handle interface.  The generic interface will use the
url-handle-* namespace.  The curl-* API provides low-level, library-specific
functions.  These functions are generally named after either a library API
(eg, `curl-easy-perform' actually accesses the resource pointed to by the
URL), or the generic API it implements (`curl-make-url-handle').

Currently there are no generic equivalents to the libcurl wrappers.  This is
intentional; I want to implement at least one more lowlevel API before
starting to design the generic APIs.

I do not have immediate plans to implement the libcurl "multi" and "shared"
interfaces.  It should be easy, and patches and suggestions are welcome.

DEFUN ("url-handle-p", Furl_handle_p, 1, 1, 0, /*
Return t if OBJECT is a URL_Handle connection. */
       (object))

DEFUN ("url-handle-type", Furl_handle_type, 1, 1, 0, /*
Return the type of URL-HANDLE, a symbol. */
       (url_handle))

DEFUN ("url-handle-live-p", Furl_handle_live_p, 1, 1, 0, /*
Return non-nil if URL_HANDLE is an active URL_HANDLE connection. */
       (url_handle))

DEFUN ("url-handle-property-list", Furl_handle_host, 1, 1, 0, /*
Return the property list of URL-HANDLE. */
       (url_handle))

DEFUN ("curl-make-url-handle", Fcurl_make_url_handle, 1, 3, 0, /*
Return a cURL handle for URL, wrapped in an url-handle.
URL is a string, which must be a URI scheme known to cURL.
URL is encoded according to optional argument CODESYS.  (Of course cURL will
URL-encode it before sending it off.)
PLIST is a property list.  These properties are set on the cURL handle.

#### This interface may change to (&rest PLIST). */
      (url, codesys, plist))

DEFUN ("curl-easy-setopt", Fcurl_easy_setopt, 3, 3, 0, /*
Set OPTION to VALUE on curl url-handle HANDLE and return t.
OPTION is a string denoting an option in `curl-option-hash-table'.
VALUE must be of the appropriate type.
HANDLE must be an url-handle object of type `curl'.
A wrapper with some validation for libcurl's `curl_easy_setopt'.
Errors without useful explanations probably mean `curl-option-hash-table'
is corrupt. */
       (option, value, handle))

DEFUN ("curl-easy-perform", Fcurl_easy_perform, 1, 2, 0, /*
Read from the URL represented by HANDLE into BUFFER at point.
Optional BUFFER defaults to the current buffer.
Returns t. */
       (handle, buffer))

DEFUN ("curl-easy-getinfo", Fcurl_easy_getinfo, 2, 2, 0, /*
Return the value of ATTRIBUTE for HANDLE.
ATTRIBUTE is a string denoting an attribute in `curl-info-hash-table'.
HANDLE must be an url-handle object of type `curl'.
A wrapper with some validation for libcurl's `curl_easy_getinfo'.
Errors without useful explanations probably mean `curl-info-hash-table'
is corrupt. */
       (attribute, handle))

DEFVAR_LISP ("curl-option-hash-table", &Vcurl_option_hash_table /*
Table of options available for `curl-easy-setopt'.
Key are strings naming options.  The option names are taken from enum
CURLoption in <curl/curl.h>.  They are all uppercase, and the "CURLOPT_"
prefix is omitted.
Values are lists containing a type symbol \(one of `long', `objectpoint',
`functionpoint', and `off_t') and an integer, which is the option index.
It is planned to add a list of Lisp types that can be converted to something
that is useful for the option as the 3rd element of the value list.
It is planned to add the leading comments as docstrings, to be the 4th
element of the value list corresponding to each key. */ );
  Vcurl_option_hash_table = Qnil;

DEFVAR_LISP ("curl-info-hash-table", &Vcurl_info_hash_table /*
Table of attributes accessible via `curl-easy-getinfo'.
Keys are strings naming attributes.  The attribute names are taken from
enum CURLinfo in <curl/curl.h>.  They are all uppercase, and the "CURLINFO_"
prefix is omitted.
Values are lists containing a type symbol (one of `long', `string',
`double', and `list') and an integer, which is the attribute index.
It is planned to add docstrings, to be the 3rd element of the value list
corresponding to each key. */ );
  Vcurl_info_hash_table = Qnil;

