Next Previous Contents

2. The Easy Interface

The ``easy'' interface consists of the functions: 

    Curl_Type curl_new (String_Type URL);
    curl_perform (Curl_Type obj);
    curl_setopt (Curl_Type obj, Int_Type op, ...);
    curl_close (Curl_Type obj);
and allows a S-lang script to transfer files is a simple synchronous manner. For example, 
     curl_perform (curl_new ("http://www.jedsoft.org/slang/"));
will cause the contents of http://www.jedsoft.org/slang/ to be retrieve via the http protocol and then written to the display.

Note that the above example makes two function calls to the curl module. The call to curl_new produces an instance of a Curl_Type object associated with the specified URL. The resulting cURL object gets passed to the curl_perform function to be processed. In this case, the default action of curl_perform causes the URL to be downloaded and then written to stdout.

The curl handles the closing and destruction of the Curl_Type object when the variable attached to it goes out of scope or gets reassigned. Nevertheless the curl_close function exists to allow the user to explicitly destroy the underlying Curl_Type object.

The curl_setopt function may be used to set options or attributes associated with a Curl_Type object. Such options influence the actions of curl_perform. For example, the CURLOPT_WRITEFUNCTION option may be used to have curl_perform pass the contents of the URL to a specified function or callback. To illustrate this, consider a callback that writes the contents of the URL to a file: 

     private define write_callback (fp, data)
     {
        variable len = bstrlen (data);
        if (len != fwrite (data, fp))
          return -1;
        return 0;
     }
In this function, fp is assumed to be an open file pointer and data is a binary string (BString_Type). The callback returns 0 if it successfully wrote the data and -1 if not. Here is how the callback can be used to download a file in MP3 format: 
     variable c = curl_new ("http://some.url.org/quixote.mp3");
     variable fp = fopen ("quixote.mp3", "wb");
     curl_setopt (c, CURLOPT_WRITEFUNCTION, &write_callback, fp);
     curl_perform (c);
     () = fclose (fp);

Often one wants to get the contents of the URL in a S-lang variable. This is easily accomplished via a callback such as: 

     private define write_variable_callback (v, data)
     {
        @v = @v + data;
        return 0;
     }
The above callback may be used as follows: 
     variable c = curl_new ("http://some.url.org/quixote.mp3");
     variable s = "";
     curl_setopt (c, CURLOPT_WRITEFUNCTION, &write_variable_callback, &s);
     curl_perform (c);
The curl_perform function passes the reference to the variable s to the callback function, which then dereferences for concatenation. After the call to curl_perform, s will be set to the contents of the URL.

Errors are handled via exceptions. If an error occurs, e.g., a host could not be contacted, or the specified URL does not exist, then a CurlError exception will be thrown. Here is an example that processes a list of URLs and prints an error if one cannot be retrieved: 

      urls = {"http://servantes.fictional.domain/don/quixote.html",
              "http://servantes.fictional.domain/sancho/panza.html"};
      foreach url (urls)
       {
         try (e)
            {
               file = path_basename (url);
               fp = fopen (file, "w");
               c = curl_new (url);
               curl_setopt (c, CURLOPT_WRITEFUNCTION, &write_callback, fp);
               curl_perform (c);
               () = fclose (fp);
            }
          catch CurlError:
            {
               vmessage ("Unable to retrieve %s: %s", url, e.message);
               () = remove (file);
            }
       }

The URLs in the above example are processed in a sequential manner. This example will be revisited in the context of the ``multi'' interface where it will be rewritten to perform a synchronous downloads.

Next Previous Contents