Next: , Previous: , Up: Reference   [Contents][Index]


2.1 Procedures

These are the procedures provided by the library.

Procedure: curl-easy-init

Returns a curl handle that you must use as input to other functions. This handle represents one connection to a server. If it fails, it will throw an error.

Procedure: curl-easy-handle? x

Returns #t if x is a curl handle such as would be created by curl-easy-handle. #f otherwise.

Procedure: curl-easy-cleanup handle

This forcibly closes all connections that this handle has used and have possibly kept open until now. Any use of the handle after it has been closed is invalid. The return value is unspecified.

Calling this procedure is optional: handles will automatically be freed when no longer in use.

Procedure: curl-easy-reset handle

Re-initializes all options previously set on a specified CURL handle to its default values. This puts back the handle to the same state as it was in when it was just created with [curl-easy-init].

It does not change the following information kept in the handle: live connections, the Session ID cache, the DNS cache, the cookies and shares.1

The return value is unspecified.

Procedure: curl-easy-perform handle #:optional bytevector? #:optional header?

From the C documentation

This function is called after the init and all the [curl-easy-setopt] calls are made, and will perform the transfer as described in the options. It must be called with the same handle as input as the [curl-easy-init] call returned.

You can do any amount of calls to [curl-easy-perform] while using the same handle. If you intend to transfer more than one file, you are even encouraged to do so. libcurl will then attempt to re-use the same connection for the following transfers, thus making the operations faster, less CPU intense and using less network resources. Just note that you will have to use [curl-easy-setopt] between the invokes to set options for the following [curl-easy-perform]

You must never call this function simultaneously from two places using the same handle. Let the function return first before invoking it another time. If you want parallel transfers, you must use several curl handles.2

With Guile-1.8, it returns a string containing the resource. The optional argument bytevector? is ignored.

With Guile-2.0, its default behavior is to return a string containing the resource. There is no way to handle the encoding of the string: the binary data will mapped byte-by-byte to a string containing codepoints U+0000 through U+00FF. If the optional bytevector? parameter is given and is set to #t, the resource will be returned as a bytevector.

It returns either a string containing the resource, a bytevector containing the resource, or #f on failure. For information about the failure, you can call curl-error-string.

If the optional header? parameter is set to #t, it returns a list of two elements. The first is a string that contains any headers, such as HTTP headers, associated with this operation. The second is the body of the request, either as a string or as a bytevector, as described above.

Procedure: curl-error-string

If a call to curl-easy-perform fails, calling this function will return information about the last error as a string.

Procedure: curl-error-code

If a call to curl-easy-perform fails, calling this function will return information about the last error as an integer. These integers come from the libcurl library and are defined in its header file <curl/curl.h>.

Procedure: curl-easy-setopt handle option info

This procedure sets the options for this handle that will describe what will happen when curl-easy-perform is called. At a minimum, curl-easy-setopt must be called at least once per handle to set the url option. option is a symbol name of an option, and info is additional information needed for the option. See Options, for a table of options and their associated required type.

important: Options for a handle are not cleared after curl-easy-perform is called. Make sure to call curl-easy-reset when you want the options for this handle to be reset.

This may throw an error if handle is already closed or if option is not the correct type.


Footnotes

(1)

from the libcurl 7.12.1 curl_easy_reset man page

(2)

from the libcurl 7.7 curl_easy_perform man page


Next: , Previous: , Up: Reference   [Contents][Index]