[Contents] [Intro] [Reference] [Tutorial] [Questions [New [Index]
Overview -> Reference -> API Reference -> How to Connect an Application

daVinci API - How to Connect an Application

From a technical point of view, communication between daVinci and a connected application program is realized with two UNIX pipes, one to send commands to the daVinci API (e.g. to transmit graphs, to attach menus/icons or to call menu functions) and one to receive the answers (e.g. return values, user events) or by bidirectional TCP/IP sockect communication, where daVinci is the socket-server and the application is the socket-client.. The following figure illustrates these approaches:

Only one application program can be connected with daVinci at a time, but this process is able to visualize many graphs in different windows (see multi-graph mode). If there is a need to have many applications communicating with daVinci in a system architecture, then the application programmer has to provide a single "concentrator process" which is between daVinci and all the applications to synchronize communication.

Communication via UNIX-pipes

Windows NT: Pipe communication will usually not work on Windows NT, because pipes don't work as expected in Tcl/Tk 8.0.3. Trying to use pipes may hang daVinci.

Choose which way to go

First of all, there are two opportunities to connect an application with daVinci's API. Either the application let daVinci do this job (this is the most easiest way) or the application connects daVinci to get more flexibility. The point is whether daVinci or the application is the parent process of the two. The advantage of the first solution, where daVinci is responsible for establishing the connection, is that the application programmer can leave the UNIX process- and pipe programming manuals on the book shelf. In this case, all an application has to do is sending commands to the API by printing on stdout and receiving the answers from the API by reading from stdin. Further, if daVinci launches the application process, the user will be able to disconnect the application later in daVinci to connect another one.

The disadvantage of this solution is that the application's stdin and stdout are exclusively reserved for communication with daVinci. If more flexibility is needed, e.g. to use other file descriptors than stdin and stdout, the application has to establish the pipe communication with daVinci on its own, read below for details.

Either daVinci connects the Application...

daVinci is able to connect an application program at start-up time using command-line option -startappl or at run-time with menu File/Connect Application.... By connecting an application, daVinci forks a new UNIX process, creates two pipes for communication, binds stdin and stdout of the new process to the end of the pipes and finally starts the specified application which has to wait for an initial ok answer before start sending commands to the API by simply printing them on stdout. Answers from the API are available for the application by reading from stdin.

At any time, the user is able to shut-down the currently connected application by selecting menu File/Disconnect Application. But this only works in case of support by the application (it has to terminate after receiving answer disconnect).

... or the Application connects daVinci

When the more comfortable connection method (described above) is not appropriate, the application program needs to start daVinci on its own. To do so, the application has to perform the following tasks:
  1. Forking a new UNIX process. This is the child process for daVinci.

  2. Creating two UNIX pipes, one to send commands and the other to receive answers from the API.

  3. Redirecting the file descriptors: stdin and stdout of the child process (daVinci) has to be connected with one side of both pipes. The parent process (application) has to connect two free file descriptors to the other end of both pipes.

  4. Calling daVinci with command-line option -pipe in the forked child process.
Note: The application has to set line-buffered I/O before start communication with daVinci via pipes. For example, in C this can be done with setbuf(stdout,NULL) and setbuf(stdin,NULL).

After establishing connection, daVinci sends an initial ok answer for synchronization. The application should not start sending commands to the API before receiving this answer. daVinci is not able to disconnect the application if it has not established the connection before. So, menu File/Disconnect Application is always deactivated for the connection method described in this paragraph.

Communication via TCP/IP sockets

Especially on Windows NT, where pipe communication doesn't work as expected, another communication mechanism is needed. TCP/IP sockets are much more flexible, than UNIX pipes. It is even possible to run daVinci and the application on different machines or different locations in the network.

Please read the above chapter on UNIX-pipes as well, because some hints that are not directly related to pipes are relevant for this communication-type as well.

Socket server daVinci

For the socket communication, daVinci always acts as the socket server by listening on a specified port for connection requests of an application. This can be initiated in two ways, first by setting the command-line option
-server or second in the File/Connect Application ... dialogs. Both ways allow the specification of the socket-port on which daVinci should listen. It is recommended to use the standard socket-port reserved exclusively for daVinci for all communications.

daVinci will listen on the specified port until a connection request is received. Than the application will be connected and the listening is stopped, because only one application can be connected to daVinci at a time. After the application has disconnected, listening will start again, if the command-line option -server has been set.

If in the File/Connect Application ... dialogs a socket-port is specified, that is not equal to the port specified with -server, daVinci will stop listening on the old port and immediately starts listening on the new port. After the application has disconnected, listening will be restarted for the port specified with -server.

The standard socket-port for daVinci

The daVinci project has reserved a standard socket-port for communications with the daVinci system at the Internet Assigned Numbers Authority (IANA). The IANA assigned port number 2542 on September, 3rd 1998 to the daVinci system.

It is recommended to use this port for all socket communications with the daVinci system, if possible.

Starting the application as a socket client

A socket client application can be started in two ways. Just start it from command-line, if daVinci has been started with command-line option -server or use menu File/Connect Application ... in the daVinci system and choose communication-type TCP/IP sockets in the second dialog.

In both cases the application is reponsible to connect to daVinci as a socket client and to set up the communication. Because this connection depends on the implementation language of the application, it's impossible to describe it in further detail. A very easy way to connect as a socket-client is available in Tcl/Tk:

  socket <hostname> <port>
This will connect the application to a socket server on host hostname and port port and delivers a file handle on which commands can be written and answers can be read.

Just try to connect the grapheditor application to daVinci by entering the following commands on command-line:

  daVinci -server &
  grapheditor -client &
This will connect the grapheditor application to daVinci as a socket client.

Transmitting Commands

After establishing connection between your application and daVinci, you should test the communication by sending command nothing several times to the API. The connection works if you receive an answer ok for each sent command. daVinci only accepts valid commands according to the
API syntax, all other messages are treated as a syntax error by sending answer communication_error(...) back to the application. Unlike previous V1.x releases, daVinci V2.x has now a robust API to continue communication after a syntax error is detected. Tip: You can play with the API by starting daVinci in a shell with option -pipe. In this case, you are able to enter (or better: using copy/paste) commands into the shell and send them to the API with one final return behind the command. The answers from the API are also displayed in the shell in this case. You can find some API examples in your daVinci distribution.

Note: API commands must not have newline or return characters inside. They must have exactly one newline at the end of the command to flush the write buffer. No other characters, even no spaces, must follow this concluding return, except of the next complete command. If these restrictions are not considered, pipe communication with the daVinci API will likely fail.


daVinci V2.1.1 Online Documentation - Page update: Oct 21, 1998