ICurl

Summary

ICurl is a wrapper for “easy” cURL interface.

Creation and destruction

To create ICurl, call CurlGet from Curl.Easy unit.

The object is ref-counted, and it will be auto-destructed when all links to it disappear.

Raw things

property Handle : TCurlHandle;

Returns cURL handle.

Set options

procedure SetOpt(aOption : TCurlOffOption; aData : TCurlOff);
procedure SetOpt(aOption : TCurlOption; aData : pointer);
procedure SetOpt(aOption : TCurlIntOption; aData : NativeUInt);
procedure SetOpt(aOption : TCurlIntOption; aData : boolean);
procedure SetOpt(aOption : TCurlStringOption; aData : PAnsiChar);
procedure SetOpt(aOption : TCurlStringOption; aData : RawByteString);
procedure SetOpt(aOption : TCurlStringOption; aData : UnicodeString);
procedure SetOpt(aOption : TCurlSlistOption; aData : PCurlSList);
          deprecated 'Use SetXXX instead: SetCustomHeaders, SetResolveList, etc.';
procedure SetOpt(aOption : TCurlPostOption; aData : PCurlHttpPost);
          deprecated 'Use SetForm or property Form instead.';

The rawmost version. Set an option.

Warning: Which options are copied and which are referenced, read cURL documentation. In 7.40.0 string options are copied, and you may freely reassign them. SList, HttpPost and other objects are referenced and thus they should not disappear until Perform ends.

procedure SetUrl(aData : PAnsiChar/RawByteString/UnicodeString);
procedure SetCaFile(aData : PAnsiChar/RawByteString/UnicodeString);

…and many-many more with string/bool/int parameters are equivalent to corresponding SetOpt.

procedure SetCustomHeaders(v : ICurlCustomSList);
procedure SetPostQuote(v : ICurlCustomSList);
procedure SetTelnetOptions(v : ICurlCustomSList);
procedure SetPreQuote(v : ICurlCustomSList);
procedure SetHttp200Aliases(v : ICurlCustomSList);
procedure SetMailRcpt(v : ICurlCustomSList);
procedure SetResolveList(v : ICurlCustomSList);
procedure SetProxyHeader(v : ICurlCustomSList);
procedure SetForm(v : ICurlCustomForm);

These functions with ICurlCustomSList, ICurlCustomForm parameters copy reference to v. You are no longer allowed to change the object, but you can…

• lose track of v (ref-counting will automatically destroy it).
• use the same object for another ICurl. The exception is ICurlCustomForm that involves streams; you should not assign it for two objects that operate simultaneously.
• Warning: cURL is not Unicode-enabled, see Unicode support for limitations.
• Warning: SetForm and SetSendStream are mutually-exclusive; when you assign one, you lose other.

procedure SetRecvStream(aData : TStream; aFlags : TCurlStreamFlags);
procedure SetSendStream(aData : TStream; aFlags : TCurlStreamFlags);
procedure SetHeaderStream(aData : TStream; aFlags : TCurlStreamFlags);

Set receiver/sender/header streams.

Flag meaning:

• csfAutoRewind: each PerformNe rewinds sender stream to 0, and sets receiver/header length to 0.
• csfAutoDestroy: after reassignment or cURL destruction the stream automatically disappears.

Warning: SetSendStream and SetForm are mutually-exclusive. If you assign one, the other will be unassigned (and probably destroyed).

Misc. functions

procedure Perform;

Performs the action. Actually does RaiseIf(PerformNe).

function PerformNe : TCurlCode;

Performs the action w/o throwing an error. The user should process error codes for himself.

procedure RaiseIf(aCode : TCurlCode);

Does nothing if aCode is OK; otherwise localizes the error message and throws an exception. Sometimes you’d like to process some errors in place w/o bulky try/except. Then you run PerformNe, manually process some errors, and do RaiseIf for everything else.

function Clone : ICurl;

Makes an exact copy, e.g. for multithreading.

Warning: Receiver, sender and header streams will be shared, but not auto-destroyed. Form, together with its streams, will be shared. So it is wise to replace all streams with unique copies for each clone. See also Unicode support.

Warning: String lists assigned via SetXXX are shared and, as they are ref-counted, destroyed when the last reference disappears. For large objects assigned via SetOpt the programmer should bother for himself about destruction.

Get info

function GetInfo(aCode : TCurlLongInfo) : longint;  overload;
function GetInfo(aInfo : TCurlStringInfo) : PAnsiChar;  overload;
function GetInfo(aInfo : TCurlDoubleInfo) : double;  overload;
function GetInfo(aInfo : TCurlSListInfo) : PCurlSList;  overload;

Return some information.

function GetResponseCode : longint;

Equivalent to GetInfo(CURLINFO_RESPONSE_CODE).