euTCP4u User Manual

by Ray Smith
ray@rays-web.com
http://rays-web.com/

Preface

This documentation is based on Philippe Jounin's copyrighted manual for the base library TCP4u. For information on TCP4u see Philippe's web page at http://philippe.jounin.net/.

License
Introduction
Installation
Examples
Function Reference
Release History

License

The base library "TCP4u" is released under the "GNU Library General Public License" (http://www.gnu.org/copyleft/lgpl.html) so I will release the Euphoria wrapper "euTCP4u" library under the same license.

euTCP4u (the wrapper for TCP4u) was written by Ray Smith and is Copyrighted by him. This library is free software; you can redistribute it and/or modify it under the terms the GNU Library General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the

Free Software Foundation, Inc.,
59 Temple Place - Suite 330,
Boston,
MA 02111-1307

Introduction

euTCP4u is a Euphoria wrapper library for a cross platform sockets library called TCP4u.

A quick description of TCP4u from the TCP4u manual:
TCP4u provides portable APIs which allow an easy use of the following IETF protocols :
The UDP protocol (RFC768),
The TCP protocol in connected mode,
The Telnet protocol (RFC764),
The HTTP 1.0 protocol (RFC1945).
The SMTP protocol such as described into the RFC821
The package contains full source code (library and samples). The DLLs and some static libraries for Windows are provided already compiled.

This release of euTCP4u doesn't cover all functions or functionality that the base library allows, most of the TCP and HTTP protocols are available, the rest will hopefully be available in the future.

Installation

Two files are required to use euTCP4u:

tcp4u.ew The Euphoria wrapper library, and
tcp4w32.dll The TCP4u dll.

The tcp4u.ew file should be in the same directory as your program or in the %EUDIR%\include directory (typically "c:\euphoria\include").

The tcp4w32.dll can be in the same directory as your program or in the system path. Typical places are in "c:\windows\system" for Windows 9x and "c:\winnt\system32" for Windows NT/2000/XP.

Examples

Once connected you can press:
'M' to get the Message Of The Day
'L' to list channels
'N' to list NAMES
'J' to join a channel called #channel
'P' to send a "dummy" private message to #channel
'ESC' to QUIT.

Simple PINGs from the server are automatically responded to using PONGS. This is by no means an IRC client. Just a test program to show that euTcp4u can connect to IRC Servers and how to perform some simple functions.

Function Reference

Tcp Related Functions:

tcp4u_error_string
tcp4u_get_listen_socket
tcp4u_accept
tcp4u_close
tcp4u_connect
tcp4u_receive
tcp4u_send
tcp4u_is_data_avail
tcp4u_flush
tcp4u_receive_until_str
tcp4u_receive_sequence
tcp4u_send_sequence

Http Related Functions:

http4u_set_buffer_size
http4u_set_timeout
http4u_error_string
http4u_get_file

Multi Purpose Functions

tcp4u_init

Description

Initialises Tcp4u. This needs to be done before you call any other Tcp4u routine.

Syntax

integer = tcp4u_init()

Returns

integer return_code

where,

return_code=	TCP4U_ERROR	(Windows only) Tcp4w has not found a correct Winsock.Dll.
	TCP4U_SUCCESS	Task is registered.

Example

if tcp4u_init() != TCP4U_SUCCESS then
   puts(1, "tcp4u_init error\n")
end if

tcp4u_cleanup

Description

Releases all resources used by Tcp4u.

Syntax

integer = tcp4u_cleanup()

Returns

integer return_code

where,

return_code=	TCP4U_ERROR	A Blocking call is in progress
	TCP4U_SUCCESS	Cleanup done

Example

integer return_code
return_code = tcp4u_cleanup() 
if return_code != TCP4U_SUCCESS then
   printf(1, "tcp4u_cleanup error '%s'\n", {tcp4u_error_string(return_code)} )
end if

tcp4u_ver

Description

Returns version information about the Tcp4u library.

Syntax

sequence = tcp4u_ver()

Returns

{ integer version_major, integer version_minor, sequence version_string }

where,

version_major=	Major version number.
version_minor=	Minor version number.
version_string=	textual description of the Tcp4u version.

Example

sequence ver

ver = tcp4u_ver()
printf(1, "...tcp4u version description='%s'\n", {ver[tcp4u_ver_string]} )
printf(1, "...tcp4u version number =%x.%x\n", { ver[tcp4u_ver_major], ver[tcp4u_ver_minor]})

tcp4u_get_local_id

Description

Returns IP information about the local computer.

Syntax

sequence = tcp4u_get_local_id()

Returns

{ 	sequence computer_name,   
	{integer ip_num1, integer ip_num2, integer ip_num3, integer ip_num4}, 
	sequence ip_description 	}

where,

computer_name=	name of the computer in network settings.
ip_num[1-4]=	the parts of an IP number.
ip_description=	the textual representation of an IP number.

Example

sequence ip_info
ip_info = tcp4u_get_local_id()

Example returned sequence:
ip_info = { "my_computer_name", {137, 172, 88, 141}, "137.172.88.141" }

Tcp Related Functions

tcp4u_error_string

Description

Returns a text message explaining Tcp4u error numbers.

Syntax

sequence = tcp4u_error_string (integer return_code)

Returns

sequence error_desc

where,

error_desc=

textual description of a return_code from a previous Tcp4u function.

Example

integer return_code
return_code = tcp4u_cleanup()
if return_code != TCP4U_SUCCESS then
   printf(1, "tcp4u_cleanup error '%s'\n", {tcp4u_error_string(return_code)} )
end if

tcp4u_get_listen_socket

Description

Opens a socket for listening. This is one of the first things a server program will do.

Syntax

sequence = tcp4u_get_listen_socket(object service, integer port, integer pending_connections)

where,

service=	The serive to be used or NULL if you specify a port (eg, "ftp", "http")
port=	The port that the application will wait for a connection on
pending_connections=	The maximum number of allowed pending connections

Returns

{ integer return_code, atom listen_socket }

where,

return_code=	TCP4U_BUFFERFREED	The pS pointer is not usable.
	TCP4U_CANCELLED	Operation has been cancelled with TcpAbort, Tcp4uCleanup or a user signal.
	TCP4U_ERROR	An unexpected error has occurred or a blocking call is in progress.
	TCP4U_NOMORESOCKET	All sockets have been used up.
	TCP4U_SUCCESS	The application is now listening for incoming connections. TcpAccept must be called to establish them.
listen_socket=		The socket value that is passed to tcp4u_accept to allow a connectoin to be established.

Example

sequence sock_listen
sock_listen = tcp4u_get_listen_socket( NULL, 17005, 1)
if sock_listen[1] != TCP4U_SUCCESS then
   printf(1, "tcp4u_get_listen_socket error '%s'\n",
		{tcp4u_error_string(sock_listen[1]), port})
else
-- continue processing
end if

tcp4u_accept

Description

Accepts an incoming request from a client to open a socket connection. An Accept is done after a tcp4u_listen_socket to allow a client to connect.

Syntax

sequence = tcp4u_accept(atom listen_socket, 	integer timeout)

where,

listen_socket=	The socket value returned by tcp4u_get_listen_socket
timeout=	The number of seconds to timeout before receiving a TCP4U_TIMEOUT return_code

Returns

{ integer return_code, atom accept_socket }

where,

return_code=	TCP4U_BUFFERFREED	The function can not write into pConnSock.
	TCP4U_CANCELLED	The call has been cancelled by TcpAbort or Tcp4uCleanup.
	TCP4U_ERROR	An unexpected error has occurred or a blocking call is in progress.
	TCP4U_TIMEOUT	A timeout occurred.
	TCP4U_SUCCESS	A connection has been requested and its descriptor is available in the pConnSocket descriptor.
accept_socket=		The socket number assigned to this connection. This is used in functions like tcp4u_send and tcp4u_receive.

Example

sequence sock_accept
sock_accept = tcp4u_accept(sock_listen[2], 30)
if sock_accept[1] != TCP4U_SUCCESS then
   if sock_accept[1] = TCP4U_TIMEOUT then
      puts(1, "You where to slow starting the client!!!!!!\n")
   else
      printf(1, "tcp4u_accept error '%s'\n", {tcp4u_error_string(sock_accept[1])} )
   end if
else
-- continue processing
end if

tcp4u_close

Description

Closes an open socket.

Syntax

integer = tcp4u_close(atom socket)

Returns

integer return_code

where,

return_code=	TCP4U_BUFFERFREED	The function can not write into pSock.
	TCP4U_ERROR	An unexpected error has occurred or a blocking call is in progress.
	TCP4U_SUCCESS	The Socket has been successfully closed. *pSock has been set to INVALID_SOCKET.

Example

integer return_code
return_code = tcp4u_close(sock_listen[2])
if return_code != TCP4U_SUCCESS then
   printf(1, "tcp4u_close error '%s'\n", {tcp4u_error_string(return_code)} )
end if

tcp4u_connect

Description

Allows a client program to connect to a remote socket that is doing a tcp4u_accept.

Syntax

sequence = tcp4u_connect(sequence server, object service, integer port)

where,

server=	The IP address of the computer you want to connect to.
service=	The service you want to use or NULL if you specify a port.
port=	The Port you want to use or NULL if you specify a service.

Returns

{integer return_code, atom connect_socket }

where,

return_code=	TCP4U_BUFFERFREED	The function can not write into pS
	TCP4U_CONNECTFAILED	The server can not be reached or no process are listening on the port.
	TCP4U_ERROR	An unexpected error has occurred or a blocking call is in progress
	TCP4U_HOSTUNKNOWN	The host has not been found in the file hosts, or the dotted address is not valid (ie: "10.10.10.543")
	TCP4U_NOMORESOCKET	All sockets have been used.
	TCP4U_SUCCESS	The connection has been established and its descriptor is available in the pS descriptor.
connect_socket=		The socket number which identifies this connection.

Example

sequence sock_connect
sock_connect = tcp4u_connect("127.0.0.1", NULL, 17005)
if sock_connect[1] != TCP4U_SUCCESS then
   printf(1, "tcp4u_connect error '%s'\n", {tcp4u_error_string(sock_connect[1])} )
else
-- continue processing
end if

tcp4u_receive

Description

Allows a program to receive data from a remote open socket.

Syntax

sequence = tcp4u_receive(atom socket, integer buff_size, integer time_out)

where,

socket=	a socket that has been opened with accept or connect
buff_size=	the number of bytes you want to receive
timeout=	how long you want to wait until a TCP4U_TIMEOUT response

Returns

{integer return_code, sequence buff}

where,

return_code=	TCP4U_BUFFERFREED	The user's buffer has been released.
	TCP4U_CANCELLED	The request has been cancelled by TcpAbort or Tcp4uCleanup.
	TCP4U_EMPTYBUFFFER	The frame is empty. (Its length is 0 byte).
	TCP4U_ERROR	An unexpected error has occurred or a blocking call is already in progress.
	TCP4U_INSMEMORY	Tcp4w can not allocate its temporary buffers.
	TCP4U_OVERFLOW	The frame to be received is greater than the user's buffer.
	TCP4U_SOCKETCLOSED	The remote host has closed its connection.
	TCP4U_SUCCESS	The length in bytes of the received frame. The frame is copied into the user's buffer except the first two bytes.
buff		The message buffer (the actual data received).

Example

sequence sock_receive
sock_receive = tcp4u_receive(sock_connect[2], 1, 1)
if sock_receive[1] = TCP4U_SUCCESS then
-- process data
else
    printf(1, "tcp4u_receive  error '%s'\n",
	    {tcp4u_error_string(sock_connect[1])} )
end if

tcp4u_send

Description

Allows a program to send data to an open remote socket.

Syntax

integer = tcp4u_send(atom socket, sequence buff)

where,

socket=	The open socket number to send the message to
buff=	The message buffer to send (the actual data to send).

Returns

integer return_code

where,

return_code=	TCP4U_CANCELLED	The request has been cancelled by TcpAbort or Tcp4uCleanup
	TCP4U_ERROR	An unexpected error has occurred or a blocking call is already in progress.
	TCP4U_INSMEMORY	Tcp4w can not allocate its temporary buffers.
	TCP4U_SUCCESS	The data have been sent.

Example

integer return_code
sequence data
data = "HELLO WORLD!"
return_code = tcp4u_send(sock_connect[2], data)
if return_code != TCP4U_SUCCESS then
   printf(1, "tcp4u_send error '%s'\n", tcp4u_error_string(return_code))
end if

tcp4u_is_data_avail

Description

Checks an open socket to see if any data is waiting to be received

Syntax

integer = tcp4u_is_data_avail(atom socket)

where,

socket=

The socket to check for available data

Returns

integer return_code

where,

return_code=	> 0	Data is available on this socket.
	= 0	No data is currently available on this socket.

Example

if tcp4u_is_data_avail(sock_connect[2]) then
-- continue processing
end if

tcp4u_flush

Description

This function empties the reception buffer for the given socket.

Syntax

integer = tcp4u_flush(atom socket)

where,

socket=

The socket to check for available data.

Returns

integer return_code

where,

return_code=	TCP4U_CANCELLED	Operation has been cancelled with TcpAbort, Tcp4uCleanup or a user signal.
	TCP4U_ERROR	An unexpected error has occurred or a blocking call is in progress.
	TCP4U_SOCKETCLOSED	The remote peer has closed its connection. No more data are to be received.
	TCP4U_SOCKETCLOSED	Reception buffer is now empty.

Example

if tcp4u_is_data_avail(sock_connect[2]) then
-- continue processing
end if

tcp4u_receive_until_str

Description

This function receives data sent by the remote station until a particular string has been received.

Syntax

sequence = tcp4u_receive_until_str(atom socket, integer buff_size, sequence stop_string, 
		integer case_sensitive, integer time_out)

where,

socket=	The socket to check for available data.
buff_size=	The maximum message size your expecting to receive.
stop_string=	The string which ends the reception.
case_sensitive=	FALSE (0) means ignore case in the stop string, TRUE (1) means don't ignore case in the stop string.
time_out=	The number of seconds to wait before a timeout is returned.

Returns

{ integer return_code, sequence buff }

where,

return_code=	TCP4U_BUFFERFREED	The user's buffer has been released.
	TCP4U_CANCELLED	The request has been cancelled by TcpAbort or Tcp4uCleanup.
	TCP4U_ERROR	An unexpected error has occurred or a blocking call is already in progress.
	TCP4U_INSMEMORY	Tcp4w can not allocate its temporary buffers.
	TCP4U_OVERFLOW	The user's buffer has been filled and the searched string has not been received.
	TCP4U_SOCKETCLOSED	The remote host has closed its connection.
	TCP4U_SUCCESS	The string has been received (all previously received bytes have been copied into the user's buffer, NOT the szStop string).
buff=		the data read from the socket.

Example

integer ret
sequence receive_seq
sequence stop_string

ret = tcp4u_receive_until_str(socket, TCP4U_MAX_MSG_SIZE, 
                        stop_string, 1, 5)
if ret[tcp4u_ret] != TCP4U_SUCCESS then
   return { ret[tcp4u_ret], {} }
else
-- continue processing
end if

tcp4u_receive_sequence

Description

Allows a program to receive a Euphoria sequence data from a remote open socket.

Syntax

sequence = tcp4u_receive_sequence(atom socket, integer time_out)

where,

socket=	a socket that has been opened with accept or connect.
timeout=	how long you want to wait until a TCP4U_TIMEOUT response.

Returns

{integer return_code, sequence buff}

where,

return_code=	TCP4U_CONVERSION_ERROR	An error occured when rebuilding the sequence (should never happen).
	TCP4U_BUFFERFREED	The user's buffer has been released.
	TCP4U_CANCELLED	The request has been cancelled by TcpAbort or Tcp4uCleanup.
	TCP4U_EMPTYBUFFFER	The frame is empty. (Its length is 0 byte).
	TCP4U_ERROR	An unexpected error has occurred or a blocking call is already in progress.
	TCP4U_INSMEMORY	Tcp4w can not allocate its temporary buffers.
	TCP4U_OVERFLOW	The frame to be received is greater than the user's buffer.
	TCP4U_SOCKETCLOSED	The remote host has closed its connection.
	TCP4U_SUCCESS	The length in bytes of the received frame. The frame is copied into the user's buffer except the first two bytes.
buff =		The message buffer (the actual data received).

Example

sequence sock_receive
sock_receive = tcp4u_receive_sequence(sock_connect[2], 1)
if sock_receive[1] = TCP4U_SUCCESS then
-- process data
else
    printf(1, "tcp4u_receive_sequence  error '%s'\n",
	    {tcp4u_error_string(sock_connect[1])} )
end if

tcp4u_send_sequence

Description

Allows a program to send a Euphoria sequence to an open remote socket.

Syntax

integer = tcp4u_send(atom socket, sequence buff)

where,

socket=	The open socket number to send the message to.
buff=	The message buffer to send (the actual data to send).

Returns

integer return_code

where,

return_code=	TCP4U_OVERFLOW	The amount of data is larger than TCP4U_MAX_MSG_SIZE
	TCP4U_CANCELLED	The request has been cancelled by TcpAbort or Tcp4uCleanup
	TCP4U_ERROR	An unexpected error has occurred or a blocking call is already in progress.
	TCP4U_INSMEMORY	Tcp4w can not allocate its temporary buffers.
	TCP4U_SUCCESS	The data have been sent.

Example

integer return_code
sequence data
data = "HELLO WORLD!"
return_code = tcp4u_send_sequence(sock_connect[2], data)
if return_code != TCP4U_SUCCESS then
   printf(1, "tcp4u_send_sequence error '%s'\n", tcp4u_error_string(return_code))
end if

Http Related Functions

http4u_set_buffer_size

Description

Sets the buffer size used when using http functions. The default buffer size is 4096 bytes.

Syntax

http4u_set_buffer_size(integer buff_size)

where,

buffer_size=

buffer size in bytes

Returns

nothing

Example

http4u_set_buffer_size(4096)

http4u_set_timeout

Description

Sets the timeout in seconds to use when using http4u functions. The default timeout is 60 seconds.??????

Syntax

http4u_set_timeout(integer seconds)

where,

seconds=

seconds to timeout for.

Returns

Nothing

Example

http4u_set_timeout(60)

http4u_error_string

Description

Returns a text message explaining Http4u error numbers.

Syntax

sequence = http4u_error_string (integer return_code)

where,

return_code=

a return_code from a previous call to a http4u funtion.

Returns

sequence error_desc

where,

error_desc=

textual description of a return_code from a previous Http4u function.

Example

see http4u_get_file

http4u_get_file

Description

Copies a file from a web server to a local drive

Syntax

integer = http4u_get_file(sequence url, object proxy, sequence filename)

where,

url=	The URL to retrieve.
proxy=	The proxy to use to get access to the web.
filename=	The local filename to save the file to.

Returns

integer	return_code

where,

return_code=	HTTP4U_BAD_PARAM	szLocalFile is NULL.
	HTTP4U_BAD_REQUEST	The HTTP rejects the request .
	HTTP4U_BAD_URL	Http4u can not process one of the given URL.
	HTTP4U_CANCELLED	A blocking call has been canceled by a TcpAbort call or by a user signal.
	HTTP4U_FILE_ERROR	Http4u can not open the destination file or write into it.
	HTTP4U_FORBIDDEN	User has no right access to this file.
	HTTP4U_INSMEMORY	Http4u can not allocate its local buffers (since it does not much memory, this should not happen !).
	HTTP4U_MOVED	The HTTP server answers that the requested file is no more at this location.
	HTTP4U_NO_CONTENT	The received file is empty.
	HTTP4U_NOT_FOUND	Requested file has not been found.
	HTTP4U_OVERFLOW	The HTTP server overflows Http4u's buffers.
	HTTP4U_PROTOCOL_ERROR	Http4u can not process the given answer.
	HTTP4U_SUCCESS	Http4u has completed the task.
	HTTP4U_TCP_CONNECT	Http4u can not establish a connection with the remote host.
	HTTP4U_TCP_FAILED	Tcp4uInit has not been called or an undetermined network error has happened.
	HTTP4U_TIMEOUT	A timeout happen during a receive call.

Example

integer return_code
return_code = http4u_get_file("http://www.rapideuphoria.com/", NULL, "c:\\tmp\\rapideuphoria.html")
if return_code != HTTP4U_SUCCESS then
   printf(1, "Error downloading file '%s'\n", {http4u_error_string(return_code)} )
end if

Release History

Version	Date	Details
1.2	15th Apr 2002	Added support for "0"'s to be received. Changed tcp4u_send() to not require a paramter for the length. The length is obtained from the length of the buffer passed. Documentation updates.
1.1	22nd Jan 2002	Added IRC test program Fixed bug where rubbish was being returned at the ned of the data.
1.0	15th Jan 2002	updated all socket variables to use atoms instead of integers. The example programs send_seq.exw and recv_seq.exw have been fixed. Updated the documentation
0.1beta	28th Sep 2000	First release

euTCP4u User Manual

Preface

Contents

License

Introduction

Installation

Examples

info.exw

get_file.exw

server.exw / client.exw

send_seq.exw / recv_seq.exw

irc_test.exw

Function Reference

Multi Purpose Functions:

Tcp Related Functions:

Http Related Functions:

Multi Purpose Functions

tcp4u_init

Description

Syntax

Returns

Example

tcp4u_cleanup

Description

Syntax

Returns

Example

tcp4u_ver

Description

Syntax

Returns

Example

tcp4u_get_local_id

Description

Syntax

Returns

Example

Tcp Related Functions

tcp4u_error_string

Description

Syntax

Returns

Example

tcp4u_get_listen_socket

Description

Syntax

Returns

Example

tcp4u_accept

Description

Syntax

Returns

Example

tcp4u_close

Description

Syntax

Returns

Example

tcp4u_connect

Description

Syntax

Returns

Example

tcp4u_receive

Description

Syntax

Returns

Example

tcp4u_send

Description

Syntax

Returns

Example

tcp4u_is_data_avail

Description

Syntax

Returns

Example

tcp4u_flush

Description