(Mattias Werner, 070998)

daVinci V2.1.1 sockets:
=======================

The new minor release of daVinci has an additional possibility to connect
applications to the daVinci API. While daVinci V2.1 only allows connections
via UNIX pipes, daVinci V2.1.1 will also act as a socket server. This
document describes the usage of sockets to connect applications to daVinci.

1. daVinci as a socket server
-----------------------------

For API connections via sockets, daVinci always acts as the socket server
and the application has to connect as a socket client. There are two ways
how to connect the socket client application to daVinci:
  - start daVinci and use the "Connect Application" dialogs to connect the
    application
  - start daVinci with command-line-option '-server' and start the application
    yourself as a new process that connects to daVinci as a socket client

2. The daVinci default port
---------------------------

The Internet Assigned Numbers Authority (IANA, http://www.iana.org/) has
assigned port number '2542' to the daVinci project for the daVinci API.
Therefore if no port number is specified, daVinci will always listen on
port 2542 for connections to its API. If this doesn't suite the needs
of an application, the port number can be changed.

3. The new "Connect Application" dialogs
----------------------------------------

In former versions of daVinci, the menu "File->Connect Application" opened
a special file selector, in which the application and its command line
options can be specified. Now this has been split into two dialogs. The
first one is just a normal file selector dialog, in which the application has
to be selected. The second dialog, which immediately opens, after selecting
the executable file of the application, allows the specification of the
communication type (UNIX-Pipes or TCP/IP Sockets), the Socket port and the
Command-Line Options.

If daVinci hasn't been started with the new '-server' command-line option,
the dialog will open with 'UNIX-Pipes' selected to achieve the same behaviour
as in former versions of daVinci. Just press 'Connect' to connect your
application via pipes or supply some command-line options before.

If 'UNIX-Pipes' is selected, the entry for the Socket Port will be disabled.

If daVinci has been started with the new '-server' command-line option, the
dialog will open with 'TCP/IP Sockets' selected. The entry for the 'Socket
Port' will contain the port number on which daVinci is listening and the
entry for the command-Line Options will already contain the option
"-client :<Socket Port>". You can change these values or just press "Connect"
to connect your application as a socket client to daVinci. The values
supplied in the entries are suitable for connecting the new grapheditor to
daVinci via sockets.

The Socket Port may be changed to any legal value (0 to 65535) but remember
that especially the ports from 0 through 1023 are reserved for services of
the operating system. Please use the daVinci default port, if possible or
look at the documents of the IANA to find out which ports are not reserved.

If daVinci already listens on a port and a new port number is specified in
the dialog, daVinci will stop listening on the old port and start listening
on the new one before forking the new subprocess with the selected application.
If an application is connected to daVinci, daVinci will stop listening for
new connections, because only one application can be connected to daVinci at
a time.

4. Command-Line option '-server ?<port>?'
-----------------------------------------

The new command-line option '-server <port>' starts daVinci as a socket server,
that immediately starts listening on the daVinci default port or the <port>
specified with the option for connection attempts of daVinci applications. Try
this on UNIX by starting daVinci and the grapheditor with the following
commands:
  % daVinci -server &
  % grapheditor -client &
You'll see that the grapheditor automatically connects to daVinci on the
daVinci default port.

The <port> specified with this option will be used as the initial value in
the second "Connect Application"-dialog described above. The <port> may be set
to any legal value (0 to 65535) but remember that especially the ports from
0 through 1023 are reserved for services of the operating system. Please use
the daVinci default port, if possible or look at the documents of the IANA to
find out which ports are not reserved.

5. The grapheditor command-line option '-client ?<hostname:port>?'
------------------------------------------------------------------

The grapheditor application contained in the daVinci distribution can act
as a socket client starting with version V2.1.1. If it is started without
the command-line option '-client', it will act as before and writes commands
to stdout and reads answers on stdin.

The command-line option '-client' to start the grapheditor as a socket client,
allows four different specifications for the host and the port number. In
opposite to the socket server, you have to specify the host of the socket
server in addition to the port number on which the server listens. This
allows you to start daVinci on one machine and the grapheditor or your own
application on another, even with different operating systems. But remember,
that you have to redirect your display, if the application displays windows
and dialogs on its own, as the grapheditor does.

The possible settings of '-client' are:
  grapheditor -client
    This starts the grapheditor as a socket client for a daVinci server
    listening on the daVinci default port 2542 on host localhost, i.e. on
    the same machine.
  grapheditor -client gemini.informatik.uni-bremen.de
    This starts the grapheditor as a socket client for a daVinci server
    listening on the daVinci default port 2542 on host
    gemini.informatik.uni-bremen.de. The hostname is any legal hostname,
    which can be reached from your machine.
  grapheditor -client :1234
    This starts the grapheditor as a socket client for a daVinci server
    listening on the port 1234 on host localhost, i.e. on the same machine.
    Don't forget to supply the ':' before the port number!
  grapheditor -client gemini:1234
    This starts the grapheditor as a socket client for a daVinci server
    listening on the port 1234 on host gemini. The hostname is any legal
    hostname, which can be reached from your machine. Don't forget to
    separate the hostname from the port with ':'!
