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

function SetOpt(aOption : TCurlOffOption; aData : TCurlOff) : ICurl;
function SetOpt(aOption : TCurlOption; aData : pointer) : ICurl;
function SetOpt(aOption : TCurlIntOption; aData : NativeUInt) : ICurl;
function SetOpt(aOption : TCurlIntOption; aData : boolean) : ICurl;
function SetOpt(aOption : TCurlStringOption; aData : PAnsiChar) : ICurl;
function SetOpt(aOption : TCurlStringOption; aData : RawByteString) : ICurl;
function SetOpt(aOption : TCurlStringOption; aData : UnicodeString) : ICurl;
function SetOpt(aOption : TCurlProxyTypeOption; aData : TCurlProxyType) : ICurl;
function SetOpt(aOption : TCurlUseSslOption; aData : TCurlUseSsl) : ICurl;
function SetOpt(aOption : TCurlFtpMethodOption; aData : TCurlFtpMethod) : ICurl;
function SetOpt(aOption : TCurlIpResolveOption; aData : TCurlIpResolve) : ICurl;
function SetOpt(aOption : TCurlRtspSeqOption; aData : TCurlRtspSeq) : ICurl;
function SetOpt(aOption : TCurlNetRcOption; aData : TCurlNetrc) : ICurl;
function SetOpt(aOption : TCurlSslVersionOption; aData : TCurlSslVersion) : ICurl;
function SetOpt(aOption : TCurlSlistOption; aData : PCurlSList) : ICurl;
          deprecated 'Use SetXXX instead: SetCustomHeaders, SetResolveList, etc.';
function SetOpt(aOption : TCurlPostOption; aData : PCurlHttpPost) : ICurl;
          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.56.1 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.

function SetUrl(aData : PAnsiChar/RawByteString/UnicodeString) : ICurl;
function SetCaFile(aData : PAnsiChar/RawByteString/UnicodeString) : ICurl;
function SetUserAgent(aData : PAnsiChar/RawByteString/UnicodeString) : ICurl;
function SetSslVerifyHost(aData : TCurlVerifyHost) : ICurl;
function SetSslVerifyPeer(aData : boolean) : ICurl;

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

function SetForm(aForm : ICurlCustomForm) : ICurl;
function SetCustomHeaders(v : ICurlCustomSList) : ICurl;
function SetPostQuote(v : ICurlCustomSList) : ICurl;
function SetTelnetOptions(v : ICurlCustomSList) : ICurl;
function SetQuote(v : ICurlCustomSList) : ICurl;
function SetPreQuote(v : ICurlCustomSList) : ICurl;
function SetHttp200Aliases(v : ICurlCustomSList) : ICurl;
function SetMailRcpt(v : ICurlCustomSList) : ICurl;
function SetResolveList(v : ICurlCustomSList) : ICurl;
function SetProxyHeader(v : ICurlCustomSList) : ICurl;
function SetConnectTo(v : ICurlCustomSlist) : ICurl;

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.

function SetProxyFromIe : ICurl;

Sets HTTP proxy server from Internet Explorer.

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).

Simple string API

Most cURL applications work with small bodies (up to 1M), and optimized memory allocation does not matter. In such a case you don’t need to create streams by yourself.

function SwitchRecvToString : ICurl;

Equivalent to SetRecvStream(TRawByteStream.Create, [csfAutoRewind, csfAutoDestroy]).

function ResponseBody : RawByteString;

If receiving stream is TRawByteStream, returns its contents. Otherwise throws an exception.

Of course, do not forget Perform between these functions, it will do all cURL’s job.

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;
function GetInfo(aInfo : TCurlStringInfo) : PAnsiChar;
function GetInfo(aInfo : TCurlDoubleInfo) : double;
function GetInfo(aInfo : TCurlSListInfo) : PCurlSList;
function GetInfo(aInfo : TCurlOffInfo) : TCurlOff;
function GetInfo(aInfo : TCurlPtrInfo) : pointer;
function GetInfo(aInfo : TCurlSocketInfo) : TCurlSocket;
function GetInfo(aInfo : TCurlDoubleInfoDeprecated) : double;
      deprecated 'Use TCurlOffInfo version';

Return some information.

function ResponseCode : longint;

Equivalent to GetInfo(CURLINFO_RESPONSE_CODE).