Class

Curl

Curl()

Constructor

# new Curl()

Create a cURL instance for HTTP requests.

Note: cURL module must be loaded by calling LoadLibrary("curl") before using!

Methods

# AddHeader(header)

Add a header in the form "Name:Value" to all requests done with this instance of Curl. If you add a header that is otherwise generated and used by libcurl internally, your added one will be used instead. If you add a header with no contents as in 'Accept:' (no data on the right side of the colon), the internally used header will get disabled. Thus, using this option you can add new headers, replace internal headers and remove internal headers. The headers must not be CRLF-terminated, because curl adds CRLF after each header item. Failure to comply with this will result in strange bugs because the server will most likely ignore part of the headers you specified.

Parameters:
Name Type Description
header string

a header to add.

# ClearHeaders()

Clear all currently used headers previously set using AddHeader().

# DoRequest(url) → {Array.<IntArray>}

perform a request with all settings previously set using the other methods.

Parameters:
Name Type Description
url string

the URL to connect to.

An array with two IntArrays and the response code. The first (index 0) contains the request body, the second (index 1) the request headers and the third (index 2) the response code.

Array.<IntArray>

# GetLastUrl() → {string}

return the last effectively used URL.

string

# GetResponseCode() → {number}

get the last generated response code.

number

# SetCaFile(cafile)

A string naming a file holding one or more certificates to verify the peer with. Default: "cacert.pem"

Parameters:
Name Type Description
cafile string

PEM cainfo file.

# SetCertificate(cert)

The string should be the file name of your certificate.

Parameters:
Name Type Description
cert string

name of the PEM cert file.

# SetCertificatePassword(cer_pw)

It will be used as the password required to use the SetCertificate() certificate.

Parameters:
Name Type Description
cer_pw string

password for key file.

# SetConnectTimeout(timeout)

It should contain the maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once it has connected, this option is of no more use. Set to zero to disable connection timeout (it will then only timeout on the system's internal timeouts). See also the SetTimeout() option.

Parameters:
Name Type Description
timeout number

the timeout in seconds.

# SetCookies(cookies)

Pass a pointer to a zero terminated string as parameter. It will be used to set a cookie in the http request. The format of the string should be NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie should contain. If you need to set mulitple cookies, you need to set them all using a single option and thus you need to concat them all in one single string. Set multiple cookies in one string like this: "name1=content1;name2=content2;" etc. Using this option multiple times will only make the latest string override the previously ones.

Parameters:
Name Type Description
cookies string

a cookie string.

# SetFollowLocation(doFollow)

A boolean parameter to tell the library to follow any Location: header that the server sends as part of a HTTP header.

Parameters:
Name Type Description
doFollow boolean

true to follow redirects, false to ignore them.

# SetGet()

Switch this Curl instance to HTTP_GET (the default).

# SetKey(key)

The string should be the file name of your private key.

Parameters:
Name Type Description
key string

name of the PEM key file.

# SetKeyPassword(key_pw)

It will be used as the password required to use the SetKey() private key.

Parameters:
Name Type Description
key_pw string

password for key file.

# SetMaxRedirs(maximum)

The set number will be the redirection limit. If that many redirections have been followed, the next redirect will cause an error (CURLE_TOO_MANY_REDIRECTS). This option only makes sense if the SetFollowLocation() is used at the same time.

Parameters:
Name Type Description
maximum number

max redirects

# SetPost(post_data)

Switch this Curl instance to HTTP_POST. post_data should be the full data to post in a HTTP post operation. This data will be sent with every request until either HTTP_POST is disabled using SetGet() or new data ist set using this method. You need to make sure that the data is formatted the way you want the server to receive it. libcurl will not convert or encode it for you. Most web servers will assume this data to be url-encoded (see urlencode()). Take note.

Parameters:
Name Type Description
post_data string

the POST data to send.

See:
  • urlencode()

# SetProxy(proxy)

Set HTTP proxy to use. The parameter should be a string holding the host name or dotted IP address. To specify port number in this string, append :[port] to the end of the host name. The proxy string may be prefixed with [protocol]:// since any such prefix will be ignored. The proxy's port number may optionally be specified with the separate function SetProxyPort().

Parameters:
Name Type Description
proxy string

the proxy.

# SetProxyPort(port)

Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string using SetProxy().

Parameters:
Name Type Description
port number

the port number.

# SetProxyUser(user_pw)

Pass a string which should be [username]:[password] to use for BASIC_AUTH the connection to the HTTP proxy.

Parameters:
Name Type Description
user_pw string

basic auth authentication string to the proxy.

# SetPut(put_data)

Switch this Curl instance to HTTP_PUT. This data will be sent with every request until either HTTP_PUT is disabled using SetGet() or new data ist set using this method.

Parameters:
Name Type Description
put_data IntArray

the PUT data to send.

# SetReferer(referer)

This string will be used to set the Referer: header in the http request sent to the remote server. This can be used to fool servers or scripts. You can also set any custom header with AddHeader().

Parameters:
Name Type Description
referer string

referer string to use.

# SetSocksProxy(isSocks)

Switch between SOCKS and HTTP proxies.

Parameters:
Name Type Description
isSocks boolean

true to use a SOCKS proxy, false for an HTTP proxy.

# SetSslVerify(verify)

Pass false to stop curl from verifying the peer's certificate.

Parameters:
Name Type Description
verify boolean

true to verify the peers certificates, false to ignore certificate errors.

# SetTimeout(timeout)

The maximum time in seconds that you allow the libcurl transfer operation to take. Normally, name lookups can take a considerable time and limiting operations to less than a few minutes risk aborting perfectly normal operations.

Parameters:
Name Type Description
timeout number

the timeout in seconds.

# SetUnrestrictedAuth(unrestricted)

A boolean parameter to tell the library it can continue to send authentication (user+password) when following locations, even when hostname changed. Note that this is meaningful only when setting SetFollowLocation(true).

Parameters:
Name Type Description
unrestricted boolean

true to no not restrict authentication, false to restrict.

# SetUserAgent(agent)

This string will be used to set the User-Agent: header in the http request sent to the remote server. This can be used to fool servers or scripts. You can also set any custom header with AddHeader(). Default: "cURL-DOjS "

Parameters:
Name Type Description
agent string

the agent string to use.

# SetUserPw(user_pw)

Pass string, which should be [username]:[password] to use for the connection. Using a colon with no password will make libcurl use an empty password. might perform several requests to possibly different hosts. libcurl will only send this user and password information to hosts using the initial host name (unless SetUnrestrictedAuth(true) is set), so if libcurl follows locations to other hosts it will not send the user and password to those. This is enforced to prevent accidental information leakage.

Parameters:
Name Type Description
user_pw string

the username/password combination to use for BASIC_AUTH.