[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). The following figure illustrates this approach:
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.

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.

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 Online Documentation - Page update: June 15, 1998