CVS update by stephent packages/unsupported/stephen/curl README

User: stephent Date: 05/11/26 17:04:25 Added: packages/unsupported/stephen/curl README Log: Project description. Revision Changes Path 1.1 XEmacs/packages/unsupported/stephen/curl/README Index: README =================================================================== 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;