libcURL.EasyHandle

libcURL.EasyHandle

Class Declaration

 Protected Class EasyHandle
 Inherits libcURL.cURLHandle

Remarks

This class wraps the curl_easy API. The "easy" moniker is more ironic than descriptive; for most transfers you probably want to use the cURLClient class to manage the EasyHandle for you. You can implement protocol-specific subclasses of EasyHandle and still use the cURLClient class to manage them (e.g. the FTPWildCard class.)

An instance of EasyHandle is a self-contained "session". It maintains its own caches, options, connections, cookies, etc., and can operate on one URL at a time. To share SSL session data, DNS caches, connection pools, and/or HTTP cookies among several instances of EasyHandle refer to the ShareHandle class; to share connections refer to the MultiHandle class.

Basic use

Create a new instance, then use the SetOption method to define what cURL will be doing.

For example, this snippet enables automatic gzip decompression of HTTP:

Dim cURL As New libcURL.EasyHandle
If Not cURL.SetOption(libcURL.Opts.ACCEPT_ENCODING, "gzip") Then
    MsgBox("cURL error: " + Str(cURL.LastError))
End If

SetOption accepts a Variant as the option value, but only certain types may be used. Setting an option value to an unsupported type will raise a TypeMismatchException.

Once all desired options have been set the transfer is ready to begin. The EasyHandle class provides a Perform method which will perform the transfer, however this method is "hard" synchronous and is not terribly useful outside of single-threaded console applications. You will almost always want to use the MultiHandle class to perform the transfer, or use the cURLClient class which will do it for you.

During a transfer, libcURL will communicate through the EasyHandle by invoking its callback methods. These shared methods invoke their associated events on the appropriate instance of EasyHandle. Refer to the documentation on each event for further details.

The DownloadStream and/or UploadStream properties supersede the DataAvailable and/or DataNeeded events, respectively. If you define a stream you must remember to set it back to Nil (or overwrite with a new stream reference) when the stream is closed.

Example

This example synchronously downloads a URL directly into a file on the user's desktop:

  Dim c As New libcURL.EasyHandle
  Dim f As FolderItem = SpecialFolder.Desktop.Child("index.html")
  Dim bs As BinaryStream = BinaryStream.Create(f, True)
  c.DownloadStream = bs
  If Not c.Perform("http://www.example.com/index.html") Then MsgBox(libcURL.FormatError(c.LastError))
  bs.Close
  c.DownloadStream = Nil ' always set to nil when complete

Event Definitions

• DataAvailable
• DataNeeded
• DebugMessage
• HeaderReceived
• Progress
• RequestInitiated
• SeekStream

Methods

• ClearFormData
• Constructor
• ErrorBuffer
• GetAuthMethods
• GetInfo
• GetOption
• Handle
• KeepAlive
• LastError
• Operator_Compare
• Pause
• Perform
• Reset
• Resume
• SetAuthMethods
• SetFormData
• SetOption
• SetOptionPtr
• SetRequestHeader

Properties

• AutoDisconnect As Boolean
• AutoReferer As Boolean
• BufferSize As Integer
• BufferSizeUpload As Integer
• CA_List As MemoryBlock
• CA_ListFile As FolderItem
• ConnectionTimeout As Integer
• ConnectionType As libcURL.ConnectionType
• CookieEngine As libcURL.CookieEngine
• CWDMethod As libcURL.CWDMethod
• DownloadStream As Writeable
• FailOnServerError As Boolean
• FollowRedirects As Boolean
• HTTPCompression As Boolean
• HTTPPreserveMethod As Boolean
• HTTPVersion As libcURL.HTTPVersion
• IPVersion As libcURL.IPVersion
• LocalPort As Integer
• MaxRedirects As Integer
• NetworkInterface As NetworkInterface
• PipeWait As Boolean
• Password As String
• Port As Integer
• ProxyEngine As libcURL.ProxyEngine
• RemoteIP As String
• RequestHeaderEngine As libcURL.RequestHeaderEngine
• ResponseHeaderEngine As libcURL.ResponseHeaderEngine
• Secure As Boolean
• SSLVersion As libcURL.SSLVersion
• Timeout As Integer
• UploadLength As Int64
• UploadMode As Boolean
• UploadStream As Readable
• URL As String
• UseErrorBuffer As Boolean
• UseProgressEvent As Boolean
• UserAgent As String
• UserName As String
• Verbose As Boolean

See also

• FTPWildCard

---

Internal API

The following methods and properties are internal to the EasyHandle and its subclasses. You don't need to worry about these unless you're modifying or subclassing the EasyHandle class.

Methods

• Destructor
• InitCallbacks
• curlDebug
• curlHeader
• curlInitRequest
• curlProgress
• curlRead
• curlSeek
• curlWrite

Shared Properties

• Instances As Dictionary

Shared Methods

• DebugCallback
• HeaderCallback
• InitRequestCallback
• ReadCallback
• SeekCallback
• WriteCallback

Delegate Methods

These delegate types cannot be instantiated directly. Rather, these are used to differentiate among, and enforce type safety for, anonymous delegates passed into the SetOption method. SetOption will automatically marshal delegates matching these signatures and reject all others. You aren't expected to understand this unless you're overriding the default callback methods.

• cURLDebugCallback
• cURLInitRequestCallback
• cURLIOCallback
• cURLProgressCallback
• cURLSeekCallback