Support libcurl

Official web site : http://curl.haxx.se/libcurl/.

Official web site : http://www.scolring.org/.

Plateform : Windows XP or +, GNU / Linux with glib > 2.x and curl dependancies should be installed

Scol : 4.0 or +

Features

Warning : at this time, this library is SYNCHRONOUS ! The asynchronous mode is to do ...
MS Windows and GNU / Linux are supported

HTTP (http://) and HTTPS (https://) request : GET, POST, PUT, with customs headers
Connection HTTP with Authentification BASIC or DIGEST
FILE (file://) protocol (typically 'get'). FILE is not authorized if the file is not in the user partition.
FTP (ftp://) to download any file

FTP (ftp://) to download and upload and some others operations

Compilation

See libcurl web site.

Flag «-lcurl» is needed. If you want, static libraries are in the "lib" subfolder.

Scol api

List of functions

ObjCurl : Scol type
_curlDsUrl : fun [ObjCurl] I - Explicit destroy
_curlNewUrl : fun [Chn S [S r1] I S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl - New simple HTTP(S) connection with GET, POST or PUT request
_curlNewUrlAuth : fun [Chn S [S I] I S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl - New HTTP connection with authentification
_curlNewFtpGet : fun [Chn S S S S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl - New FTP connection to retrieve a file from a server (download)
_curlNewFtpPut : fun [Chn S S [[S I] r1] S S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl - New FTP connection to store a local file to a server (upload)
_curlNewFtp : fun [Chn S [[S I] r1] S S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl - New FTP connection to send any FTP's commands to a server (generic)
_curlNewSFtp : - New SFTP connection (FTP with SSH)
_curlNewSmtp : fun [Chn S S [S r1] S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl - New SMTP connection (typacally, send an email)
_curlNewSmtpEx : - New SMTP connection with TLS and others options

ObjCurl

ObjCurl is a new type

It describes an active connection.

_curlNewUrl

_curlNewUrl is a function to send a "basic" HTTP(S) request : GET, POST or PUT

Prototype

Prototype : _curlNewUrl
Return	Type	Name	Description
fun [Chn S [S r1] I S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl
-	Chn	channel	a channel in which the connection will be created
-	S	url	any url (correct). Not tested before.
-	[S r1]	headers	any list of header, if you want (otherwise, nil and the default header are used).
-	I	mode	The request mode : 0 = GET (default), 1 = POST, 2 = PUT. PUT hasn't been tested !! This can be dangeurous (server security) If a secured connection (https) is used, this function verify the parameter (certificate ...). Not to verify, you should set the mode to 10, 11 or 12 (GET, POST or PUT)
-	S	datas	Any datas to send
-	fun [ObjCurl u0 S I S S] u1	callback	This callback will run each server response packet. See below too
-	u0	user_param	a parameter, at your convenience (used to the callback)
ObjCurl	-	-	New scol object

Prototype : callback
Return	Type	Name	Description
fun [ObjCurl u0 S I S S] u1
-	ObjCurl	object	Scol object for this connection
-	u0	user_param	Your parameter, at your convenience. Defined to the «_curlNewUrl» function.
-	S	response	The received data to the server
-	I	size	The size of the received data
-	S	url	The initial url
-	S	error	The error message (if error), human readable
u1	-	-	a return at your convenience

Examples

Basic GET

Save a web page from a server :

typeof curl = ObjCurl;;
typeof filew = W;;

fun cbCurl (obj, user_param, data, size, url, err)=
	_fooS user_param;
	_fooI size;
	_fooS url;
	_fooS err;
	_appendpack data filew;
	0;;

fun main ()=
	_showconsole;

	set filew = _getmodifypack "tests/curl_result.txt";
	_createpack "" filew;

	set curl = _curlNewUrl
                _channel
                "http://www.example.com/page.txt"
                nil
                0
                nil
                @cbCurl
                "my user parameter";

	_curlDsUrl curl;

	0;;

Note : the url can not use the file:// protocol : "file://c:\\folder\\file.ext" is unauthorized (for security reasons) because the file is not in the scol user partition. However, "file:///home/iri/Logiciels/scol/partition/logo.bmp" can be authorized if the current Scol directory is "/home/iri/Logiciels/scol/".

Note 2 : the url can use the ftp protocol : "htp://username:password@ftpserver/directory/file.ext" will download file.ext.

Basic POST

Send a name and a pseudonym via a HTTP POST request. The response is saved to a file.

typeof curl = ObjCurl;;
typeof filew = W;;

fun cbCurl (obj, user_param, data, size, url, err)=
	_fooS user_param;
	_fooI size;
	_fooS url;
	_fooS err;
	_appendpack data filew;
	0;;

fun main ()=
	_showconsole;

	set filew = _getmodifypack "tests/vrac/curl_result.txt";
	_createpack "" filew;

	set curl = _curlNewUrl
                _channel
                "http://www.example.com/test.php"
                nil
                1
                "name=steph&pseudo=iri"
                @cbCurl
                "my user parameter";

	_curlDsUrl curl;
	0;;

The PHP script could be at the server :

<?php
$name = htmlspecialchars ($_POST["name"]);
$pseudo = htmlspecialchars ($_POST["pseudo"]);
?>
<html>
<body>
<p>The name is : <?php echo $name; ?>.</p>
<p>The pseudo is : <?php echo $pseudo; ?>.</p>
</body>
</html>

Basic PUT

Send a file to a server.

typeof curl = ObjCurl;;

fun cbCurl (obj, user_param, data, size, url, err)=
	_fooS user_param;
	_fooI size; /* size already sent */
	_fooS url;
	_fooS err;
	0;;

fun main ()=
	_showconsole;

	set curl = _curlNewUrl
                _channel
                "http://www.example.com/put.php"
                nil
                1
                "/home/iri/file.txt"
                @cbCurl
                "my user parameter";

	_curlDsUrl curl;
	0;;

You should set to Apache (if you use Apache, of course) the «Script» directive (in the <Directory> block or directly in a <VirtualHost>, more information http://www.apacheweek.com/features/put) :

Script PUT /put.php

The basic "put.php" script could be ... :

$putdata = fopen ("php://input", "r");
$fp = fopen ("myputfile.ext", "w");
while ($data = fread ($putdata, 1024))
fwrite ($fp, $data);
fclose ($fp);
fclose ($putdata);

_curlNewUrlAuth

Perform a new connection with authentification (basic or digest)

Prototype

Prototype : _curlNewUrlAuth
Return	Type	Name	Description
fun [Chn S [S r1] [S I] I S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl
-	Chn	channel	a channel in which the connection will be created
-	S	url	any url (correct). Not tested before.
-	[S r1]	headers	any list of header, if you want (otherwise, nil and the default header are used).
-	[S I]	tuple	The string is the login : «username:password» ; the integer is the authentification mode : 0 : any, 1 : basic, 2 : digest. By default, ANY is used : libcurl choose the best solution.
-	I	mode	The request mode : 0 = GET (default), 1 = POST, 2 = PUT. PUT hasn't been tested !! This can be dangeurous (server security)
-	S	datas	Any datas to send
-	fun [ObjCurl u0 S I S S] u1	callback	This callback will run each server response packet. See below too
-	u0	user_param	a parameter, at your convenience (used to the callback)
ObjCurl	-	-	New scol object

Prototype : callback
Return	Type	Name	Description
fun [ObjCurl u0 S I S S] u1
-	ObjCurl	object	Scol object for this connection
-	u0	user_param	Your parameter, at your convenience. Defined to the «_curlNewUrlAuth» function.
-	S	response	The received data to the server
-	I	size	The size of the received data
-	S	url	The initial url
-	S	error	The error message (if error), human readable
u1	-	-	a return at your convenience

Example

With a BASIC authentification ...

typeof curl = ObjCurl;;
typeof filew = W;;

fun cbCurl (obj, user_param, data, size, url, err)=
	_fooS user_param;
	_fooI size;
	_fooS url;
	_fooS err;
	_appendpack data filew;
	0;;

fun main ()=
	_showconsole;

	set filew = _getmodifypack "tests/vrac/curl_result.txt";
	_createpack "" filew;

	set curl = _curlNewUrlAuth
                _channel
                "http://www.example.com/rep/"
                ["bob:1234" 0]
                0
                nil
                @cbCurl
                "toto";

	_curlDsUrl curl;

	0;;

_curlNewFtpGet

Retreive a file from a server (by ftp)

Prototype

Prototype : _curlNewFtpGet
Return	Type	Name	Description
fun [Chn S S S S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl
-	Chn	channel	a channel in which the connection will be created
-	S	url	an url (can contain directory, like "ftp.server.com/rep_1/rep_2/"). If the last / is omitted, it will be added. If the protocol is absent (ftp://), it will be added too.
-	S	file	the file to download. It can contain some directories, like "rep_1/rep_2/file.ext". No "/" at the first character !
-	S	username	the username to the conection on this server. If anonymous, you must set it to nil (not "" !)
-	S	password	the password to the conection on this server. If anonymous, you must set it to nil (not "" !)
-	fun [ObjCurl u0 S I S S] u1	callback	This callback will run each server response packet. See below too
-	u0	user_param	a parameter, at your convenience (used to the callback)
ObjCurl	-	-	New scol object

Prototype : callback
Return	Type	Name	Description
fun [ObjCurl u0 S I S S] u1
-	ObjCurl	object	Scol object for this connection
-	u0	user_param	Your parameter, at your convenience. Defined to the «_curlNewFtpGet» function.
-	S	response	The received data to the server
-	I	size	The size of the received data
-	S	url	The initial url
-	S	error	The error message (if error), human readable
u1	-	-	a return at your convenience

Example

Retrieve a file from the gnu ftp server. This server accepts a anonymous's connection only.

typeof curl = ObjCurl;;
typeof filew = W;;

fun cbCurl (obj, user_param, data, size, url, err)=
	_fooS user_param;
	_fooI size;
	_fooS strcat "url = " url;
	_fooS strcat "err = " err;
	_appendpack data filew;
	0;;

fun main ()=
	_showconsole;

	set filew = _getmodifypack "tests/vrac/curl_result.txt";
	_createpack "" filew;

	set curl = _curlNewFtpGet
                _channel
                "ftp.gnu.org/gnu/"
                "=README"
                nil
                nil
                @cbCurl
                "my user parameter";
        ...
	0;;

_curlNewFtpPut

Store a local file (upload) to a server(by ftp)

Prototype

Prototype : _curlNewFtpPut
Return	Type	Name	Description
fun [Chn S S [S r1] S S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl
-	Chn	channel	a channel in which the connection will be created
-	S	url	an url (can contain directory, like "ftp.server.com/rep_1/rep_2/"). If the last / is omitted, it will be added. If the protocol is absent (ftp://), it will be added too.
-	S	file	the local file to download. It can contain some directories, like "rep_1/rep_2/file.ext". No "/" at the first character ! The dest filename is the basename of the local file
-	[[S I] r1]	commands	any commands to send to the server AFTER (if the second item is 1) or BEFORE (if the second item is 0) the transfert (can be nil). To know all commands, see RFC959
-	S	username	the username to the conection on this server. If anonymous, you must set it to nil (not "" !)
-	S	password	the password to the conection on this server. If anonymous, you must set it to nil (not "" !)
-	fun [ObjCurl u0 S I S S] u1	callback	This callback will run each server response packet. See below too
-	u0	user_param	a parameter, at your convenience (used to the callback)
ObjCurl	-	-	New scol object

Prototype : callback
Return	Type	Name	Description
fun [ObjCurl u0 S I S S] u1
-	ObjCurl	object	Scol object for this connection
-	u0	user_param	Your parameter, at your convenience. Defined to the «_curlNewFtpPut» function.
-	S	response	The received data to the server
-	I	size	The size of the received data
-	S	url	The initial url
-	S	error	The error message (if error), human readable
u1	-	-	a return at your convenience

Example

Delete a file on the server, upload the local file "logo.bmp" (at the scol root directory) and rename it to the server.

typeof curl = ObjCurl;;
typeof filew = W;;

fun cbCurl (obj, user_param, data, size, url, err)=
	_fooS user_param;
	_fooI size;
	_fooS strcat "url = " url;
	_fooS strcat "err = " err;
	_appendpack err filew;
	0;;

fun main ()=
	_showconsole;

	set filew = _getmodifypack "tests/vrac/curl_result.txt";
	_createpack "" filew;

	set curl = _curlNewFtpPut
                _channel
                "ftp.example.com"
                "logo.bmp"
                ["RNFR logo.bmp" 1] :: ["RNTO scol_logo.bmp" 1] :: ["DELE bob.png" 0] :: nil
                "mylogin"
                "mypassword"
                @cbCurl
                "my user parameter";
	...

	0;;

_curlNewFtpPut

Run any ftp's commands on the server

Prototype

Prototype : _curlNewFtp
Return	Type	Name	Description
fun [Chn S [[S I] r1] S S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl
-	Chn	channel	a channel in which the connection will be created
-	S	url	an url (can contain directory, like "ftp.server.com/rep_1/rep_2/"). If the last / is omitted, it will be added. If the protocol is absent (ftp://), it will be added too.
-	[[S I] r1]	commands	any commands to send to the server. The second item, an integer, is not used yet. To know all the commands, see RFC959 or send the command HELP to the server.
-	S	username	the username to the conection on this server. If anonymous, you must set it to nil (not "" !)
-	S	password	the password to the conection on this server. If anonymous, you must set it to nil (not "" !)
-	fun [ObjCurl u0 S I S S] u1	callback	This callback will run each server response packet. See below too
-	u0	user_param	a parameter, at your convenience (used to the callback)
ObjCurl	-	-	New scol object

Prototype : callback
Return	Type	Name	Description
fun [ObjCurl u0 S I S S] u1
-	ObjCurl	object	Scol object for this connection
-	u0	user_param	Your parameter, at your convenience. Defined to the «_curlNewFtp» function.
-	S	response	The received data to the server
-	I	size	The size of the received data
-	S	url	The initial url
-	S	error	The error message (if error), human readable
u1	-	-	a return at your convenience

Example

This example send two commands to the gnu's server (anonymous user only) and save the responses to two local files.

typeof curl = ObjCurl;;
var n = 0;;

fun cbCurl (obj, user_param, data, size, url, err)=
	_fooS user_param;
	_fooI size;
	_fooS strcat "url = " url;
	_fooS strcat "err = " err;
	let _getmodifypack strcatn "tests/vrac/curl_result_" :: (itoa n) :: ".txt" :: nil -> filew in
	_appendpack data filew;
	0;;

fun main ()=
	_showconsole;

	set curl = _curlNewFtp
                _channel
                "ftp.gnu.org/gnu/"
                ["LIST" 1] :: ["RETR =README" 1] :: nil
                nil
                nil
                @cbCurl
                "my parameter";
    ...
	0;;

_curlNewSmtp

Run any ftp's commands on the server

Prototype

Prototype : _curlNewSmtp
Return	Type	Name	Description
fun [Chn S S [S r1] S fun [ObjCurl u0 S I S S] u1 u0] ObjCurl
-	Chn	channel	a channel in which the connection will be created
-	S	server	the SMTP server (domain or ip)
-	S	from	from (emitter)
-	[S r1]	to	to (destinataire)
-	S	body	the body
-	fun [ObjCurl u0 S I S S] u1	callback	This callback will run each server response packet. See below too
-	u0	user_param	a parameter, at your convenience (used to the callback)
ObjCurl	-	-	New scol object

Prototype : callback
Return	Type	Name	Description
fun [ObjCurl u0 S I S S] u1
-	ObjCurl	object	Scol object for this connection
-	u0	user_param	Your parameter, at your convenience. Defined to the «_curlNewSmtp» function.
-	S	response	The received data to the server
-	I	size	The size of the received data
-	S	url	The initial url
-	S	error	The error message (if error), human readable
u1	-	-	a return at your convenience

Example

This example send a basic email.

typeof curl = ObjCurl;;

fun main ()=
	_showconsole;

	set curl = _curlNewFtpPut
                _channel
                "smtp.example.com"
                "bob"
                "alice@example.com" :: "william@example.com" :: nil
                "It is a simple test, thanks"
                nil
                0;
	...
	0;;

_curlDsUrl

Destroy a Scol ObjCurl object.

Prototype

Prototype : _curlDsUrl
Return	Type	Name	Description
fun [ObjCurl] I
-	ObjCurl	object	The object to destroy
I	-	-	0 if success, nil otherwise (see log for more information)