diff options
| -rw-r--r-- | doc/ivy-perl-1.html | 116 | ||||
| -rw-r--r-- | doc/ivy-perl-2.html | 44 | ||||
| -rw-r--r-- | doc/ivy-perl-3.html | 111 | ||||
| -rw-r--r-- | doc/ivy-perl-4.html | 28 | ||||
| -rw-r--r-- | doc/ivy-perl-5.html | 23 | ||||
| -rw-r--r-- | doc/ivy-perl-6.html | 35 | ||||
| -rw-r--r-- | doc/ivy-perl-7.html | 25 | ||||
| -rw-r--r-- | doc/ivy-perl.html | 66 | ||||
| -rw-r--r-- | doc/ivy-perl.sgml | 377 |
9 files changed, 377 insertions, 448 deletions
diff --git a/doc/ivy-perl-1.html b/doc/ivy-perl-1.html deleted file mode 100644 index b6b2c92..0000000 --- a/doc/ivy-perl-1.html +++ /dev/null @@ -1,116 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> - <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> - <TITLE>The Ivy Perl library guide: General information</TITLE> - <LINK HREF="ivy-perl-2.html" REL=next> - - <LINK HREF="ivy-perl.html#toc1" REL=contents> -</HEAD> -<BODY> -<A HREF="ivy-perl-2.html">Next</A> -Previous -<A HREF="ivy-perl.html#toc1">Contents</A> -<HR> -<H2><A NAME="s1">1. General information</A></H2> - -<H2><A NAME="ss1.1">1.1 What is Ivy?</A> -</H2> - -<P> -<P>Ivy is a software bus designed at CENA (France). A software bus is a system -that allows software applications to exchange information with the illusion of -broadcasting that information, selection being performed by the receiving -applications. Using a software bus is very similar to dealing with events in a -graphical toolkit: on one side, messages are emitted without caring about who -will handle them, and on the other side, one decide to handle the messages that -have a certain type or follow a certain pattern. Software buses are mainly aimed -at facilitating the rapid development of new agents, and at managing a dynamic -collection of agents on the bus: agents show up, emit messages and receive some, -then leave the bus without blocking the others. -<P> -<H3>Architecture and principles</H3> - -<P>As opposed to other software buses, Ivy does not depend on a centralised -server. Actually, Ivy is mostly a communication convention between processes, -implemented through a collection of libraries in several languages. -<P> -<P> -<P>From the programmer's point of view, Ivy is an information broadcasting -channel. The main functions are: -<P> -<UL> -<LI> connecting to a bus.<EM> Example: Ivy::start (-loopMode => - 'local', -ivyBus => '2011', -appName => "toto" );</EM></LI> -<LI> sending a message.<EM> Example: Ivy::sendMsgs ("HELLO WORLD")</EM></LI> -<LI> bind a message pattern to a callback function.<EM> Example: - Ivy::bindRegexp ("^HELLO (.*)", [\&cb])</EM></LI> -<LI> the main loop.<EM> MainLoop</EM></LI> -</UL> -<P>Ivy's -decentralised connection scheme probably incurs limitations in terms of how many -applications can be connected to an Ivy bus, but this simplifies management a -lot. Basically, an Ivy bus is just a set of applications that decide to -communicate together. The only conventions between these applications are: -<OL> -<LI> the use of the Ivy protocol (for obvious reasons)</LI> -<LI> a bus address, made of a broadcast port number (a bit like a citizen band -channel) and a set of networks addresses</LI> -</OL> - -When an application wants to connect to a bus, it sends a broadcast message on the -networks specified in the bus address, so that all applications present on those -networks and listening on the specified port number connect to it. It then -becomes part of the bus, and listens like the other ones. -<P>The messages are exchanged in text format, and bindings are based on regular -expressions with captures. If an application subscribes to -<CODE>HELLO (.*)</CODE> and if another application emits the message <CODE>HELLO WORLD</CODE>, a -callback will be called in the first application with <CODE>WORLD</CODE> as an argument. -<P> -<P> -<H3>Using Ivy</H3> - -<P>You can use Ivy through applications that have been provided to you. This is the -case for <CODE>ivyprobe</CODE>, an Ivy agent that allows you to examine the messages -exchanged on a given bus and to send messages on that bus. You can refer to the -web site <CODE>http:</CODE> for a list of available agents. However, what you will -usually want to do is to develop your own applications. In order to do that you -can use an Ivy connection kit, that is a library that implements Ivy. -<P> -<P> -<P>Libraries that implement Ivy are available in the following environments: -<UL> -<LI> in C on Unix and Windows platforms, with its own communication library</LI> -<LI> in C++ on Windows platforms</LI> -<LI> in C++ on Unix platforms, integrated with the Uch communication library</LI> -<LI> in C++ on Unix platforms, integrated with OpenInventor</LI> -<LI> in C++ on Macintosh</LI> -<LI> in Perl and in Perl/Tk</LI> -<LI> integrated with Object Caml on Unix platforms</LI> -<LI> in Scheme on Unix platforms</LI> -<LI> in Java</LI> -</UL> -<P> -<P>Connecting your application to an Ivy bus just consists in choosing the -appropriate library, add the appropriate message emission and reception calls to -your code, use the main loop provided in the library or make the necessary -integrations, and get your code running! -<P> -<H2><A NAME="ss1.2">1.2 The Ivy Perl library</A> -</H2> - -<P>The Ivy Perl library (aka Ivy-Perl or ivy-perl) is a Perl library that allows you to connect -applications to an Ivy bus. You can use it to write applications in Perl or any -other language that supports Perl extensions (Perl/Tk for instance). This guide documents how you can do -that. -<P>The Ivy Perl library is known to compile and work in WindowsNT and Linux -environments. It should be easy to use on most Posix environments. -<P>The Ivy Perl library was originally developed by Alexandre Bustico at CENA. It -is maintained by the CENA-Toulouse team. -<P> -<HR> -<A HREF="ivy-perl-2.html">Next</A> -Previous -<A HREF="ivy-perl.html#toc1">Contents</A> -</BODY> -</HTML> diff --git a/doc/ivy-perl-2.html b/doc/ivy-perl-2.html deleted file mode 100644 index 50b58ff..0000000 --- a/doc/ivy-perl-2.html +++ /dev/null @@ -1,44 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> - <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> - <TITLE>The Ivy C library guide: Getting and installing the Ivy Perl library</TITLE> - <LINK HREF="ivy-perl-3.html" REL=next> - <LINK HREF="ivy-perl-1.html" REL=previous> - <LINK HREF="ivy-perl.html#toc2" REL=contents> -</HEAD> -<BODY> -<A HREF="ivy-perl-3.html">Next</A> -<A HREF="ivy-perl-1.html">Previous</A> -<A HREF="ivy-perl.html#toc2">Contents</A> -<HR> -<H2><A NAME="s2">2. Getting and installing the Ivy Perl library</A></H2> - -<P>You can get the latest versions of the Ivy Perl library from CENA (http://XXX) or -from one of the Fairway sites (for instance http://XXX). Depending whether you -use a supported distribution of Linux or not, you have the following options: -<P> -<H2><A NAME="ss2.1">2.1 Installing RedHat or Debian packages</A> -</H2> -<p>If your system is Linux/Redhat, you have to use the command <em><strong> rpm -i package-name</strong></em>. -<p>If your system is Linux/Debian, you have to use the command <em><strong> dpkg -i package-name</strong></em>. - - -<P> -<P> -<H2><A NAME="ss2.2">2.2 Getting and installing the sources</A> -</H2> -<p>If your system is not a Linux one, you have to get and install the source of ivy-perl. -In this case, you have to get the source from CENA at http://XXX or from one of the Fairway sites. - - -<P> -<P> -<P> -<P> -<HR> -<A HREF="ivy-perl-3.html">Next</A> -<A HREF="ivy-perl-1.html">Previous</A> -<A HREF="ivy-perl.html#toc2">Contents</A> -</BODY> -</HTML> diff --git a/doc/ivy-perl-3.html b/doc/ivy-perl-3.html deleted file mode 100644 index bee7734..0000000 --- a/doc/ivy-perl-3.html +++ /dev/null @@ -1,111 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> - <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> - <TITLE>The Ivy C library guide: Basic functions</TITLE> - <LINK HREF="ivy-perl-4.html" REL=next> - <LINK HREF="ivy-perl-2.html" REL=previous> - <LINK HREF="ivy-perl.html#toc3" REL=contents> -</HEAD> -<BODY> -<A HREF="ivy-perl-4.html">Next</A> -<A HREF="ivy-perl-2.html">Previous</A> -<A HREF="ivy-perl.html#toc3">Contents</A> -<HR> -<H2><A NAME="s3">3. Basic functions</A></H2> - -<H2><A NAME="ss3.1">3.1 Initialization and main loop</A> -</H2> - -<P>Initializing an Ivy agent with the Ivy-Perl library is done by calling function <CODE>Ivy::start</CODE>. In theory, initialization is then over. However in -practice, as for any asynchronous communication or interaction library, nothing -happens until your application has reached the main loop. -<P>The Ivy Perl library provides two kind of main loop: a "local" loop - for perl code, and a "Tk" loop for perl-tk code. -<P>Here is more details on <CODE>Ivy::start</CODE> function: -<P> -<BLOCKQUOTE><CODE> -<PRE> - Ivy::start(-loopMode => 'TK', - -ivyBus => '2011', - -appName => "TOTO", - -neededApp => "TITI", - -statusFunc => \&statusScan); - -</PRE> -</CODE></BLOCKQUOTE> - -initializes and connects your application to the bus specified in <CODE>ivyBus</CODE>. The string provided -should follow the convention described in section XX. Example: <CODE>"127:2010"</CODE>.. -<P> - -<BLOCKQUOTE><CODE> -<PRE> -MainLoop; -</PRE> -</CODE></BLOCKQUOTE> - -makes your application enter the main loop in which it will handle asynchronous -communications and signals. -<P> -<BLOCKQUOTE><CODE> -<PRE> -Ivy::stop (); -</PRE> -</CODE></BLOCKQUOTE> - -makes your application exit the main loop. -<P> -<P> -<H2><A NAME="ss3.2">3.2 Emitting messages</A> -</H2> - -<P>Emitting a message on an Ivy bus is much like printing a message on the standard -output. However, do not forget that your message will not be emitted if Ivy has -not been properly initialized and if you do not have a main loop of some sort -running. To emit a message, use <CODE>IvySendMsg</CODE>, which works like <CODE>printf</CODE>: -<P> -<BLOCKQUOTE><CODE> -<PRE> -Ivy::sendMsg ("..."); -</PRE> -</CODE></BLOCKQUOTE> - -sends a message on the bus. -<P> -<P> -<H2><A NAME="ss3.3">3.3 Subscribing to messages</A> -</H2> - -<P>Subscribing to messages consists in binding a callback function to a message -pattern. Patterns are described by regular expressions with captures. When a -message matching the regular expression is detected on the bus, the callback -function is called. The captures (ie the bits of the message that match the -parts of regular expression delimited by brackets) are passed to the callback -function much like options are passed to <CODE>main</CODE>. Use function <CODE>Ivy::bindRegexp</CODE> -to bind a callback to a pattern. -<BLOCKQUOTE><CODE> -<PRE> -Ivy::bindRegexp ("^HELLO WORLD", [\&Start]); -</PRE> -</CODE></BLOCKQUOTE> - -binds callback function <CODE>Start</CODE> to the regular expression specified by -<CODE>regex_format</CODE>. -<P> -<BLOCKQUOTE><CODE> -<PRE> -Ivy::bindRegexp ("^HELLO WORLD", NULL); -</PRE> -</CODE></BLOCKQUOTE> - -deletes the binding. -<P> -<P> -<P> -<HR> -<A HREF="ivy-perl-4.html">Next</A> -<A HREF="ivy-perl-2.html">Previous</A> -<A HREF="ivy-perl.html#toc3">Contents</A> -</BODY> -</HTML> diff --git a/doc/ivy-perl-4.html b/doc/ivy-perl-4.html deleted file mode 100644 index 88719cc..0000000 --- a/doc/ivy-perl-4.html +++ /dev/null @@ -1,28 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> - <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> - <TITLE>The Ivy C library guide: Advanced functions</TITLE> - <LINK HREF="ivy-perl-5.html" REL=next> - <LINK HREF="ivy-perl-3.html" REL=previous> - <LINK HREF="ivy-perl.html#toc4" REL=contents> -</HEAD> -<BODY> -<A HREF="ivy-perl-5.html">Next</A> -<A HREF="ivy-perl-3.html">Previous</A> -<A HREF="ivy-perl.html#toc4">Contents</A> -<HR> -<H2><A NAME="s4">4. Advanced functions</A></H2> - -<H2><A NAME="ss4.1">4.1 Utilities</A> -</H2> - -<H2><A NAME="ss4.2">4.2 Direct messages</A> -</H2> - -<HR> -<A HREF="ivy-perl-5.html">Next</A> -<A HREF="ivy-perl-3.html">Previous</A> -<A HREF="ivy-perl.html#toc4">Contents</A> -</BODY> -</HTML> diff --git a/doc/ivy-perl-5.html b/doc/ivy-perl-5.html deleted file mode 100644 index 96276ea..0000000 --- a/doc/ivy-perl-5.html +++ /dev/null @@ -1,23 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> - <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> - <TITLE>The Ivy C library guide: Managing timers and other channels</TITLE> - <LINK HREF="ivy-perl-6.html" REL=next> - <LINK HREF="ivy-perl-4.html" REL=previous> - <LINK HREF="ivy-perl.html#toc5" REL=contents> -</HEAD> -<BODY> -<A HREF="ivy-perl-6.html">Next</A> -<A HREF="ivy-perl-4.html">Previous</A> -<A HREF="ivy-perl.html#toc5">Contents</A> -<HR> -<H2><A NAME="s5">5. Managing timers and other channels</A></H2> - -<P> -<HR> -<A HREF="ivy-perl-6.html">Next</A> -<A HREF="ivy-perl-4.html">Previous</A> -<A HREF="ivy-perl.html#toc5">Contents</A> -</BODY> -</HTML> diff --git a/doc/ivy-perl-6.html b/doc/ivy-perl-6.html deleted file mode 100644 index 9d31b44..0000000 --- a/doc/ivy-perl-6.html +++ /dev/null @@ -1,35 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> - <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> - <TITLE>The Ivy C library guide: Conventions for writing applications</TITLE> - <LINK HREF="ivy-perl-7.html" REL=next> - <LINK HREF="ivy-perl-5.html" REL=previous> - <LINK HREF="ivy-perl.html#toc6" REL=contents> -</HEAD> -<BODY> -<A HREF="ivy-perl-7.html">Next</A> -<A HREF="ivy-perl-5.html">Previous</A> -<A HREF="ivy-perl.html#toc6">Contents</A> -<HR> -<H2><A NAME="s6">6. Conventions for writing applications</A></H2> -<H3>6.1 Default bus</H3> -By default, the bus used is <em><strong>127.255.255.255:2010 </em></strong> ie the application will be connected on the port 2010 of the local machine it runs on.</p> -<P>You can set the bus to be used by setting the environment variable <CODE>IVYBUS</CODE> or by implementing the option <CODE>-b</CODE> in the application.</P> -<P> -<H3>6.2 Syntax of messages</h3> -The syntax of the messages exchanged is totally free. However, the following convention is recommended: -<menu> -<li>The message syntax is <CODE>Subject Attributes</CODE></li> -<li>A Subject is an object, named in a hierarchical form: <CODE>ObjectClass1:object1.ObjectClass2:object2...</CODE></li> -<li>Attributes are pairs <CODE>(attribute-name, value)</CODE></li> -</menu> -Example: -<p><CODE>AIRCRAFT:LIB720 Moved lat=46.1697 lon=2.0844 vx=-36 vy=-463 afl=330 rate=0 heading=184 ground_speed=465 -mach_speed=0 tendance=0 time=24600 cfl=330</CODE> -<HR> -<A HREF="ivy-perl-7.html">Next</A> -<A HREF="ivy-perl-5.html">Previous</A> -<A HREF="ivy-perl.html#toc6">Contents</A> -</BODY> -</HTML> diff --git a/doc/ivy-perl-7.html b/doc/ivy-perl-7.html deleted file mode 100644 index c46da20..0000000 --- a/doc/ivy-perl-7.html +++ /dev/null @@ -1,25 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> - <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> - <TITLE>The Ivy C library guide: Known bugs</TITLE> - <LINK HREF="ivy-perl-6.html" REL=previous> - <LINK HREF="ivy-perl.html#toc7" REL=contents> -</HEAD> -<BODY> -Next -<A HREF="ivy-perl-6.html">Previous</A> -<A HREF="ivy-perl.html#toc7">Contents</A> -<HR> -<H2><A NAME="s7">7. Known bugs</A></H2> -<p>This version is only compatible with perl-tk 402-004. -<p>It does not work with perl-tk 400.202 (fileId event problem) -<p>It does not work with perl-tk_800.011 (remove file descriptor problem) - - -<HR> -Next -<A HREF="ivy-perl-6.html">Previous</A> -<A HREF="ivy-perl.html#toc7">Contents</A> -</BODY> -</HTML> diff --git a/doc/ivy-perl.html b/doc/ivy-perl.html deleted file mode 100644 index 58b8ea1..0000000 --- a/doc/ivy-perl.html +++ /dev/null @@ -1,66 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<HTML> -<HEAD> - <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.7"> - <TITLE>The Ivy Perl library guide</TITLE> - <LINK HREF="ivy-perl-1.html" REL=next> - - -</HEAD> -<BODY> -<A HREF="ivy-perl-1.html">Next</A> -Previous -Contents -<HR> -<H1>The Ivy Perl library guide</H1> - -<H2>Stéphane Chatty, <CODE>chatty@cena.dgac.fr</CODE></H2>13 April 1999 -<P><HR> -<EM>This document is a programmer's guide that describes how to use the Ivy Perl -library to connect applications to an Ivy bus. This guide describes version 3.0 -of the library.</EM> -<HR> -<P> -<H2><A NAME="toc1">1.</A> <A HREF="ivy-perl-1.html">General information</A></H2> - -<UL> -<LI><A HREF="ivy-perl-1.html#ss1.1">1.1 What is Ivy?</A> -<LI><A HREF="ivy-perl-1.html#ss1.2">1.2 The Ivy Perl library</A> -</UL> -<P> -<H2><A NAME="toc2">2.</A> <A HREF="ivy-perl-2.html">Getting and installing the Ivy Perl library</A></H2> - -<UL> -<LI><A HREF="ivy-perl-2.html#ss2.1">2.1 Installing RedHat or Debian packages</A> -</UL> -<P> -<H2><A NAME="toc3">3.</A> <A HREF="ivy-perl-3.html">Basic functions</A></H2> - -<UL> -<LI><A HREF="ivy-perl-3.html#ss3.1">3.1 Initialization and main loop</A> -<LI><A HREF="ivy-perl-3.html#ss3.2">3.2 Emitting messages</A> -<LI><A HREF="ivy-perl-3.html#ss3.3">3.3 Subscribing to messages</A> -<LI><A HREF="ivy-perl-3.html#ss3.4">3.4 Example</A> -</UL> -<P> -<H2><A NAME="toc4">4.</A> <A HREF="ivy-perl-4.html">Advanced functions</A></H2> - -<UL> -<LI><A HREF="ivy-perl-4.html#ss4.1">4.1 Utilities</A> -<LI><A HREF="ivy-perl-4.html#ss4.2">4.2 Direct messages</A> -</UL> -<P> -<H2><A NAME="toc5">5.</A> <A HREF="ivy-perl-5.html">Managing timers and other channels</A></H2> - - -<P> -<H2><A NAME="toc6">6.</A> <A HREF="ivy-perl-6.html">Conventions for writing applications</A></H2> - -<P> -<H2><A NAME="toc7">7.</A> <A HREF="ivy-perl-7.html">Known bugs</A></H2> -<HR> -<A HREF="ivy-perl-1.html">Next</A> -Previous -Contents -</BODY> -</HTML> diff --git a/doc/ivy-perl.sgml b/doc/ivy-perl.sgml new file mode 100644 index 0000000..31b39f5 --- /dev/null +++ b/doc/ivy-perl.sgml @@ -0,0 +1,377 @@ +<!-- + The Ivy Perl library guide + + Copyright (c) 1999-2000 + Centre d'Etudes de la Navigation Aerienne + + SGML source file + + Authors: Stéphane Chatty <chatty@cena.dgac.fr> + + $Id$ + + Please refer to file Ivy.pm for the + copyright notice regarding this software +--> + +<!-- ------------------------------------------------------------------------------- + This file was rebuilt from html files after the disappearance of the + original sgml file. It is not yet syntactically valid, and documents an + old version of Ivy Perl. + ------------------------------------------------------------------------------- --> + +<?xml version='1.0' ?> +<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> + +<article> +<artheader> + +<title>The Ivy Perl library guide</title> + +<authorgroup> +<author> +<firstname>Stéphane</firstname><surname>Chatty</surname> +<affiliation><address><email>chatty@cena.fr</email></address></affiliation> +</author> +</authorgroup> +<date>April 13, 1999</date> + +<copyright> +<year>1999</year> +<holder>Centre d'Études de la Navigation Aérienne</holder> +</copyright> + +<abstract> +<para> +This document is a programmer's guide that describes how to use the Ivy Perl +library to connect applications to an Ivy bus. This guide describes version 3.0 +of the library. The Ivy Perl library was mainly written by Alexandre Bustico +from CENA, but this documentation is maintained by users of the library. +</para> +</abstract> +</artheader> + +<sect1> +<title>Foreword</title> + +<para> +This document was written in SGML according to the DocBook DTD, so as to be able to +generate PDF and html output. However, the authors have not yet mastered the +intricacies of SGML, the DocBook DTD, the DocBook Stylesheets and the related +tools, which have achieved the glorious feat of being far more complex than +LaTeX and Microsoft Word combined together. This explains why this document, in addition +to being incomplete, is so ugly. We'll try and improve it. +</para> +</sect1> + + +<sect1> +<title>What is Ivy?</title> +<para> +Ivy is a software bus designed at CENA (France). A software bus is a system +that allows software applications to exchange information with the illusion of +broadcasting that information, selection being performed by the receiving +applications. Using a software bus is very similar to dealing with events in a +graphical toolkit: on one side, messages are emitted without caring about who +will handle them, and on the other side, one decide to handle the messages that +have a certain type or follow a certain pattern. Software buses are mainly aimed +at facilitating the rapid development of new agents, and at managing a dynamic +collection of agents on the bus: agents show up, emit messages and receive some, +then leave the bus without blocking the others. +</para> + + +<sect2> +<title>Architecture and principles</title> + +<para> +As opposed to other software buses, Ivy does not depend on a centralised +server. Actually, Ivy is mostly a communication convention between processes, +implemented through a collection of libraries in several languages. +</para> + +<para> +From the programmer's point of view, Ivy is an information broadcasting +channel. The main functions are: + +<UL> +<LI> connecting to a bus.<EM> Example: Ivy::start (-loopMode => + 'local', -ivyBus => '2011', -appName => "toto" );</EM></LI> +<LI> sending a message.<EM> Example: Ivy::sendMsgs ("HELLO WORLD")</EM></LI> +<LI> bind a message pattern to a callback function.<EM> Example: + Ivy::bindRegexp ("^HELLO (.*)", [\&cb])</EM></LI> +<LI> the main loop.<EM> MainLoop</EM></LI> +</UL> +</para> + +<para> +Ivy's decentralised connection scheme probably incurs limitations in terms of +how many applications can be connected to an Ivy bus, but this simplifies +management a lot. Basically, an Ivy bus is just a set of applications that +decide to communicate together. The only conventions between these applications +are: +<OL> +<LI> the use of the Ivy protocol (for obvious reasons)</LI> +<LI> a bus address, made of a broadcast port number (a bit like a citizen band +channel) and a set of networks addresses</LI> +</OL> +</para> + +<para> +When an application wants to connect to a bus, it sends a broadcast message on the +networks specified in the bus address, so that all applications present on those +networks and listening on the specified port number connect to it. It then +becomes part of the bus, and listens like the other ones. +</para> + +<para> +The messages are exchanged in text format, and bindings are based on regular +expressions with captures. If an application subscribes to +<CODE>HELLO (.*)</CODE> and if another application emits the message <CODE>HELLO WORLD</CODE>, a +callback will be called in the first application with <CODE>WORLD</CODE> as an argument. +</para> + +</sect2> + +<sect2> +<title>Using Ivy</title> +<para> +You can use Ivy through applications that have been provided to you. This is the +case for <CODE>ivyprobe</CODE>, an Ivy agent that allows you to examine the +messages exchanged on a given bus and to send messages on that bus. You can +refer to the web site <CODE>http://www.tls.cena.fr/products/ivy/</CODE> for a +list of available agents. However, what you will usually want to do is to +develop your own applications. In order to do that you can use an Ivy connection +kit, that is a library that implements Ivy. +</para> + +<para> +Libraries that implement Ivy are available in the following environments: +<UL> +<LI> in C on Unix and Windows platforms, with its own communication library</LI> +<LI> in C++ on Windows platforms</LI> +<LI> in C++ on Unix platforms, integrated with the Uch communication library</LI> +<LI> in C++ on Unix platforms, integrated with OpenInventor</LI> +<LI> in C++ on Macintosh</LI> +<LI> in Perl and in Perl/Tk</LI> +<LI> integrated with Object Caml on Unix platforms</LI> +<LI> in Scheme on Unix platforms</LI> +<LI> in Java</LI> +</UL> +</para> + +<para> +Connecting your application to an Ivy bus just consists in choosing the +appropriate library, add the appropriate message emission and reception calls to +your code, use the main loop provided in the library or make the necessary +integrations, and get your code running! +</para> +</sect1> + +<sect1> +<title>The Ivy Perl library</title> + +<sect2> +<title>What is it?</title> + +<para> +The Ivy Perl library (aka Perl-Net-Ivy or ivy-perl) is a Perl library that +allows you to connect applications to an Ivy bus. You can use it to write +applications in Perl or any other language that supports Perl extensions +(Perl/Tk for instance). This guide documents how you can do that. +</para> + +<para> +The Ivy Perl library is known to compile and work in WindowsNT and Linux +environments. It should be easy to use on most Posix environments. +</para> + +<para> +The Ivy Perl library was originally developed by Alexandre Bustico at CENA. It +is maintained by the CENA-Toulouse team. +</para> + + + +<sect2> +<title>Getting and installing the Ivy Perl library</title> + +<para> +You can get the latest versions of the Ivy C library from CENA +(<ulink URL="http://www.tls.cena.fr/products/ivy/">http://www.tls.cena.fr/products/ivy/</ulink>). Depending +on whether you use a supported binary distribution, you can retrieve RPM +or Debian packages for Linux (do not forget to get the development package as +well as the run-time package), or retrieve the source files and install them by hand. +If your packages are Linux/RPM, you have to use the command <em><strong> rpm -i package-name</strong></em>. +If your system is Linux/Debian, you have to use the command <em><strong> dpkg -i package-name</strong></em>. +</para> +</sect2> +</sect1> + +<sect1> +<title>Basic functions</title> + +<sect2> +<title>Initialization and main loop</title> + +<para> +Initializing an Ivy agent with the Ivy-Perl library is done by calling function +<CODE>Ivy::start</CODE>. In theory, initialization is then over. However in +practice, as for any asynchronous communication or interaction library, nothing +happens until your application has reached the main loop. +</para> + +<para> +The Ivy Perl library provides two kind of main loop: a "LOCAL" loop + for perl code, and a "TK" loop for perl-Tk code. +</para> + +<para> +Here is more details on <CODE>Ivy::start</CODE> function: + +<programlisting> + Ivy::start(-loopMode => 'TK', + -ivyBus => '2011', + -appName => "TOTO", + -neededApp => "TITI", + -statusFunc => \&statusScan); +</programlisting> + +initializes and connects your application to the bus specified in +<CODE>ivyBus</CODE>. The string provided should follow the convention described +in section XX. Example: <CODE>"127:2010"</CODE>.. +</para> + +<para> +<programlisting> +MainLoop; +</programlisting> + +makes your application enter the main loop in which it will handle asynchronous +communications and signals. +</para> + +<para> +<programlisting> +Ivy::stop (); +</programlisting> + +makes your application exit the main loop. +</para> + +<sect2> +<title>Emitting messages</title> + +<para> +Emitting a message on an Ivy bus is much like printing a message on the standard +output. However, do not forget that your message will not be emitted if Ivy has +not been properly initialized and if you do not have a main loop of some sort +running. To emit a message, use <CODE>IvySendMsg</CODE>, which works like +<CODE>printf</CODE>: +</para> + +<para> +<programlisting> +Ivy::sendMsg ("..."); +</programlisting> + +sends a message on the bus. +</para> + + +<sect2> +<title>Subscribing to messages</title> + +<para> +Subscribing to messages consists in binding a callback function to a message +pattern. Patterns are described by regular expressions with captures. When a +message matching the regular expression is detected on the bus, the callback +function is called. The captures (ie the bits of the message that match the +parts of regular expression delimited by brackets) are passed to the callback +function much like options are passed to <CODE>main</CODE>. Use function +<CODE>Ivy::bindRegexp</CODE> to bind a callback to a pattern. + +<programlisting> +Ivy::bindRegexp ("^HELLO WORLD", [\&Start]); +</programlisting> + +binds callback function <CODE>Start</CODE> to the regular expression specified by +<CODE>regex_format</CODE>. +</para> + +<para> +<programlisting> +Ivy::bindRegexp ("^HELLO WORLD", NULL); +<programlisting> + +deletes the binding. +</para> + +</sect1> + +<sect1> +<title>Advanced functions</title> + +<sect2> +<title>Utilities</title> +</sect2> + +<sect2> +<title>Direct messages</title> +</sect2> + +</sect1> + +<sect1> +<title>Managing timers and other channels</title> +</sect1> + +<sect1> +<title>Conventions for writing applications</title> + +<sect2> +<title>Default bus</title> +<para> +By default, the bus used is <em><strong>127.255.255.255:2010 </em></strong> ie +the application will be connected on the port 2010 of the local machine it runs +on. +</para> + +<para> +You can set the bus to be used by setting the environment variable +<CODE>IVYBUS</CODE> or by implementing the option <CODE>-b</CODE> in the +application. +</para> + +<sect2> +<title>Syntax of messages</title> +<para> +The syntax of the messages exchanged is totally free. However, the following +convention is recommended: +<menu> +<li>The message syntax is <CODE>Subject Attributes</CODE></li> +<li>A Subject is an object, named in a hierarchical form: <CODE>ObjectClass1:object1.ObjectClass2:object2...</CODE></li> +<li>Attributes are pairs <CODE>(attribute-name, value)</CODE></li> +</menu> +</para> + +<para> +Example: + +<programlisting> +AIRCRAFT:LIB720 Moved lat=46.1697 lon=2.0844 vx=-36 vy=-463 afl=330 rate=0 heading=184 ground_speed=465 mach_speed=0 tendance=0 time=24600 +</programlisting> +</para> + +</sect1> + +<sect1> +<title>Known bugs</title> +<para> +Version 3 is only compatible with perl-tk 402-004. +It does not work with perl-tk 400.202 (fileId event problem) +It does not work with perl-tk_800.011 (remove file descriptor problem) +</para> +</sect1> +</article> + |