3.3 Using the low-level interface

Using hURL's low-level interface is more difficult than using the high-level interface because it allows you to access curl's APIs directly. This means that you should first make yourself familiar with curl's API so that you know how it is designed and how it can serve your purposes.

Basically, using a curl API directly involves the following three steps:

  1. Create a curl object handle, e.g. a curl easy handle.
  2. Do something with the handle, e.g. start a transfer.
  3. Destroy the handle.

For example, to transfer a file using curl's easy interface, you could use the following code:

 
@REQUIRE "hurl"

; this function will be called whenever there is new data
Function p_WriteData(data$)
   WriteBytes(1, data$)
EndFunction

OpenFile(1, "test.html", #MODE_WRITE)

; create easy object and configure it
e = hurl.Easy({URL = "https://www.paypal.com/", WriteFunction =
        p_WriteData, FollowLocation = True})

; transfer data
e:Perform()

; destroy easy object
e:Close()
CloseFile(1)

The code above downloads the page at https://www.paypal.com/ and saves it to the file test.html using curl's easy interface. It does so by first creating an easy object using hurl.Easy() and then setting the options #CURLOPT_URL, #CURLOPT_WRITEFUNCTION, and #CURLOPT_FOLLOWLOCATION on that easy object.

As shown above, curl options can be set directly when creating curl objects. Alternatively, you can also create an empty curl object and set the options afterwards, like so:

 
e = hurl.Easy()
e:SetOpt_URL("https://www.paypal.com/")
e:SetOpt_WriteFunction(p_WriteData)
e:SetOpt_FollowLocation(True)

This code does the same thing as the code in corresponding section above. The only difference is that options aren't set at creation time but after creation. Furthermore, you can also set multiple options at once after object creation. Here is another alternative for the two code snippets above:

 
e = hurl.Easy()
e:SetOpt({URL = "https://www.paypal.com/", WriteFunction = p_WriteData,
            FollowLocation = True})

Finally, you can also use easy:SetOpt() to set curl options on curl easy handles. So there is even a fourth way of doing what the code snippets above do. Here it is:

 
e = hurl.Easy()
e:SetOpt(#CURLOPT_URL, "https://www.paypal.com/")
e:SetOpt(#CURLOPT_WRITEFUNCTION, p_WriteData)
e:SetOpt(#CURLOPT_FOLLOWLOCATION, True)

For more information on the function of curl's various options, please refer to the following chapters.


Show TOC