5. Coserver

5.1 What are coservers		The use of coservers in Serveez
5.2 Writing coservers		How to write coservers with Serveez
5.3 Existing coservers		What kind of coservers already exist ?

5.1 What are coservers

If it is necessary to complete blocking tasks in Serveez you have to use coservers. The actual implementation differs on platforms. On Unices they are implemented as processes communicating with Serveez over pipes. On Win32 Serveez uses threads and shared memory.

5.2 Writing coservers

5.2.1 Making and configuring preparations

First you have to change into the `src/libserveez/coserver/' directory of the Serveez package. Then edit the `Makefile.am' and add your header and implementation file to the libcoserver_la_SOURCES variable.

5.2.2 Coserver header file

You have to declare the coserver handle routine here. This callback gets the input buffer argument and delivers the output buffer result. Both of these buffers are supposed to be lines separated by a `\n'.

5.2.3 Coserver implementation file

Here you need to #include "libserveez/coserver/coserver.h" and implement the coserver handle routine declared in the coserver header file. This can be any blocking system call. On successful completion you can return the result or NULL on errors. The input and output buffers are plain strings and can have any format with one exception. Because the coservers communicate via a line protocol with Serveez these buffers must not contain `\n' (0x0d).

5.2.4 Make your coserver available in Serveez

For this you have to edit `coserver.h' and `coserver.c' files which are located in the `src/libserveez/coserver/' directory. In the header file you have to define a further COSERVER_* id (macro) and set the MAX_COSERVER_TYPES define to the appropriate value. Then you should define a further svz_coserver_* macro in the same file.

In `coserver.c' you have to implement the svz_coserver_* macro. This macro takes three arguments. The first is always specific to your coserver and is used to create the actual request string. Then follows the result callback routine, and an optional argument for this callback. The latter two are simply passed to the svz_coserver_send_request() routine. This routine takes four arguments where the first is the previously defined COSERVER_* id and the second is the input buffer for the coserver handle routine without the trailing `\n'.

Then you need to add your coserver to the svz_coservertypes array specifying the COSERVER_* id, the coserver description, the coserver handle routine discussed above, the number of coserver instances to be created and an optional initialization routine.

5.3 Existing coservers

5.3.1 Identification (Ident) coserver

The Identification protocol is briefly documented in RFC1413. It provides a means to determine the identity of a user of a particular TCP connection. Given a TCP port number pair, it returns a character string which identifies the owner of that connection on the server's (that is the client's) system.

This is a connection based application on TCP. A server listens for TCP connections on TCP port 113 (decimal). Once a connection is established, the server reads a line of data which specifies the connection of interest. If it exists, the system dependent user identifier of the connection of interest is sent as the reply. The server may then either shut down the connection or it may continue to read/respond to more queries.

The Ident coserver is a client to this kind of service. For every established network connection you can use this service by calling the appropriate macro from `coserver.h'. But you could also use the Ident coserver as is without this macro. The messages from Serveez to this coserver are formatted this way:

Format: RemoteAddressInDottedDecimals ":" RemotePort ":" LocalPort Macro: svz_coserver_ident (sock, MyIdentCallback, sock->id, sock->version);

In this context sock is of type svz_socket_t and MyIdentCallback is something like the following example. Both of the last two (optional) arguments identify a valid socket structure and user can be NULL if there is no ident daemon running on the foreign machine. The last two argument within the above macro will be the last two arguments in the callback below. Thus you will know what kind of data the invocation of the callback is related to.

Callback: int MyIdentCallback (char *user, int id, int version) { printf ("Identified user: %s\n", user); return 0; }

5.3.2 Domain Name Server (DNS) coserver

The DNS coserver is using gethostbyname() to translate a given hostname to the associated IP address. The format of the coserver input line and the macro from `coserver.h' is shown below. The IRC server is currently using this coserver for resolving its `?-Lines'. See section 4.4 Existing servers, for more information. In the example below realhost is something like `www.textsure.net'.

Format: RemoteHostname Macro: svz_coserver_dns (realhost, irc_connect_server, ircserver, NULL); Callback: int irc_connect_server (char *ip, irc_server_t *server) { printf ("The ip address is: %s\n", ip); return 0; }

5.3.3 Reverse Domain Name Server (reverse DNS) coserver

As easily guessed from the name this coserver is just doing the reverse as the DNS coserver. It translates a given IP address into a hostname using gethostbyaddr(). In the macro the ip address is given as an unsigned long in host byte order. The Reverse DNS coserver itself takes something like `192.168.2.1'.

Format: RemoteAddressInDottedDecimals Macro: svz_coserver_reverse (addr, MyReverseCallback, sock->id, sock->version); Callback: int MyReverseCallback (char *host, int id, int version) { printf ("Hostname is: %s\n", host); return 0; }