
* +---------------------------------------------------------+ *
* | Easy Socket library - version 0.1                       | *
* | (C) 1999-2000, Erich Roncarolo <erich@roncarolo.eu.org> | *
* +---------------------------------------------------------+ *


This library supplies some functions to bind and connect socket,
and to read and write variables of all simple types and strings.
It's written in C, but there is also an interface for PHP3.


LIBRARY:
~~~~~~~
In the library there are two function to bind and connect socket

 int easy_tcp_bind(char *host, int port, int backlog);
 int easy_tcp_connect(char *host, int port);

that return a socket handler that can be used usually.

There are also two functions to read and write each data type:

 <type> read_<type>(int sock);
 int write_<type>(int sock, <type> <data>);

These functions works very well sending data as is through the socket.
If reader and writer use, for example, integer of 16 bits (reader) and
integer of 32 bits (writer) you should use another function:

 int write_<type>_c(int sock, <type> <data>);

that convert data in a string of fixed size before send it. Then you can
read data with:

 <type> read_<type>_c(int sock);

that return a data of the correct type after reading the string.
See "easy_sock.h" for functions details.

Obviously, you can always use standard read() and write() functions:

 ssize_t read(int sock, void *buf, size_t count);
 ssize_t write(int sock, const void *buf, size_t count);


BUGS:
~~~~
This library ignores endian issues.


INSTALLATION:
~~~~~~~~~~~~
To compile library:
# make

To run the first test:
# make test

To compile and link a program that depends from this library:
# gcc -I/path/to/dir/that/contains/easy_sock.h -I- \
  -L/path/to/dir/that/contains/libeasy_sock.a -leasy_sock \
  -o program program.c

To run program just linked you should add the directory:
 /path/to/dir/that/contains/libeasy_sock.so
to LD_LIBRARY_PATH, than you can execute it. This way doesn't work if your
program is setuid/setgid binary (LD_LIBRARY_PATH is ignored).
Another way is to copy (or to link) libeasy_sock.so in /lib or /usr/lib.
 

To compile and *statically* link a program that uses this library:
# gcc -I/path/to/dir/that/contains/easy_sock.h -I- \
  -static /path/to/easy_sock.o -o program program.c

If you want to link this library with your program, but you don't want
statically link other libraries, you should compile it like this:
# gcc -I/path/to/dir/that/contains/easy_sock.h -I- \
  /path/to/easy_sock.o -o program program.c


TEST:
~~~~
There are 3 program to test library:

 1. easy_test
 2. easy_server
 3. easy_client

First one is a simple test (you can see it with 'make test'), while other
ones are a server and a client that should work together.

To compile and run server, simply type:
# make server

To compile and run client, type:
# make client

Server usage: easy_server [host port]
 It bind host:port and wait for connections. When accept a connection it
 read a command, then execute it.
 Two command are available:
  <x> read <type> <var>
  <x> write <type> <var> <value>
 Where <x> can be '-' or 'c': first one tell to server to use normal
 functions, and second one tell to use 'chars' functions.
 <type> is one of {char, short, int, long, float, double, string}.
 <var> is a number from 0 to MAX_VAR-1, <value> must be coerent with type.
 Only MAX_VARS (actually 100) variables for each type can be written.

Client usage: easy_client [host port] <x> <read|write> <type> <var> [value]
 It works like server. The library is linked with the program, so you can use
 it directly, without change libraries path. Obviously it needs easy_server.


PHP3:
~~~~
There are a PHP3 Easy Socket version: this includes the library file
(easy_sock.php3) and a test file (easy_client.php3).
You can use it with Apache if the PHP3 module is installed; just load
the following URL in your favourite browser:
 http://localhost/path/to/Easy/Socket/library/easy_client.php3

It needs easy_server to work.


TUNNEL:
~~~~~~
In library is included an example of applicaction called "tunnel".
It binds an host:port pair and create a tunnel that links it with another
host:port pair.

Compilation:
# make tunnel

Usage: tunnel host1 port1 host2 port2

Like the easy_client, the library is linked with the program.


LICENSE:
~~~~~~~
Easy Socket library is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published
by the Free Software Foundation; either version 2 of the License, or
(at your option) any later version as specified in file LICENSE.


                     Erich Roncarolo
                     <erich@roncarolo.eu.org>

