diff options
| -rw-r--r-- | doc/ivy-c.sgml | 62 |
1 files changed, 29 insertions, 33 deletions
diff --git a/doc/ivy-c.sgml b/doc/ivy-c.sgml index 7365746..bd0be09 100644 --- a/doc/ivy-c.sgml +++ b/doc/ivy-c.sgml @@ -40,14 +40,14 @@ <date>December 11, 2002</date> <copyright> -<year>1998-2002</year> +<year>1998-2006</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 C -library to connect applications to an Ivy bus. This guide describes version 3.2 +library to connect applications to an Ivy bus. This guide describes version 3.8 of the library. </para> </abstract> @@ -90,7 +90,7 @@ library, please refer to <citetitle>The Ivy sofware bus: a white paper</citetitle>. If you want more details about the internals of Ivy, have a look at <citetitle>The Ivy architecture and protocol</citetitle>. And finally, if you are more interested in other languages, refer to other guides such as -<citetitle>The Ivy Perl library guide</citetitle>. All those documents should be +<citetitle>The Ivy Java library guide</citetitle>. All those documents should be available from the Ivy Web site at <ulink URL="http://www.tls.cena.fr/products/ivy/">http://www.tls.cena.fr/products/ivy/</ulink>. </para> </sect1> @@ -108,7 +108,7 @@ Ivy bus. This guide is here to help you do that. </para> <para> -The Ivy C library is known to compile and work in WindowsNT and Linux +The Ivy C library is known to compile and work in Win32, Linux, and MacOSX environments. It should be easy to use on most Posix environments. </para> @@ -125,8 +125,8 @@ is maintained by a group at CENA (Toulouse, France) 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 binary 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 compile them. +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 compile them. </para> </sect2> @@ -151,8 +151,8 @@ Here is the code of "hellotranslater.c": #include <stdlib.h> #include <stdio.h> #include <getopt.h> -#include <ivy.h> -#include <ivyloop.h> +#include <Ivy/ivy.h> +#include <Ivy/ivyloop.h> /* callback associated to "Hello" messages */ void HelloCallback (IvyClientPtr app, void *data, int argc, char **argv) @@ -195,7 +195,7 @@ main (int argc, char**argv) IvyBindMsg (ByeCallback, 0, "^Bye$"); /* main loop */ - IvyMainLoop (0); + IvyMainLoop (0,0); } </programlisting> @@ -308,14 +308,15 @@ environment variable is not defined, the default value <parameter>"127:2010"</parameter> is used. <programlisting> -void IvyMainLoop (void (*hook) (void)); +void IvyMainLoop (void (*beforehook) (void),void (*afterhook) (void)); </programlisting> makes your application enter the main loop in which it will handle asynchronous communications and signals. This is the default Ivy main loop, based on the <function>select</function> POSIX system call. -If non-null, <parameter>hook</parameter> is called every time the main loop is +If non-null, <parameter>beforehook</parameter> is called every time the main loop is about to enter <function>select</function>, and can be used (with care!) to -extend the main loop. +extend the main loop. <parameter>afterhook</parameter> is called each time the +main loop exits <function>select</function>. <programlisting> void IvyStop (); @@ -346,7 +347,9 @@ sends a message on the bus. This function has exactly the same behaviour as <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 +pattern. Patterns are described by regular expressions with captures. Since +the 3.6 library, we use <ulink url="http://www.pcre.org/">Perl Compatible Regular +Expression</ulink>. 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 @@ -397,7 +400,10 @@ typedef void (*MsgCallback)(IvyClientPtr app, void *data, int argc, char **argv) <sect2> <title>Direct messages</title> <para> -[to be written] +There are cases when we don't want to send messages to every other subscribee +on the bus. Direct messages allow peer to peer communication, and thus kind of +break the software bus metaphor. We strongly discourage you to use them, and +thus won't provide handy documentation. </para> </sect2> @@ -587,21 +593,11 @@ int main(int argc,char *argv[]){ <sect2> <title>Using Ivy with Tcl/Tk</title> -<para>Just load the libtclivy.so package, and use the following commands -<programlisting> -#!/usr/bin/tclsh -Ivy::init $name $hellomessge connectproc dieproc -Ivy::start $domain -Ivy::bind $regexp ballback -Ivy::applist -Ivy::send $message -Ivy::applist -mainloop -</programlisting> +<para> A full example in Tcl/Tk is provided here: <programlisting> #!/usr/bin/wish -load libtclivy.so.3.4 +load libtclivy.so.3 proc connect {args} { } proc send { } { global tosend @@ -622,12 +618,12 @@ pack .send </sect2> <sect2> -<title>Using Ivy with Gtk</title> +<title>Using Ivy with Gtk/Gdk</title> <para>There is little to do to make your gtk applications Ivy aware: just add the following lines into your code: <programlisting> -#include <ivy.h> -#include <ivygtkloop.h> +#include <Ivy/ivy.h> +#include <Ivy/ivyglibloop.h> ... IvyInit ("IvyGtkButton", "IvyGtkButton READY",NULL,NULL,NULL,NULL); IvyBindMsg(textCallback,&tosend,"^Ivy Button text=(.*)"); @@ -636,12 +632,12 @@ IvyStart (bus); </para> <para>A full example: gtkIvyButton.c is provided below, compile it with the --lgtkivy flag. The other flags depend on your system installation ( replace -pkg-config with gtk-config for older gnome1 libs) +appropriate flags for your gtk distribution ( `pkg-config --cflags --libs +gtk+-x11-2.0 `) and -lglibivy . <programlisting> #include <gtk/gtk.h> -#include <ivy.h> -#include <ivygtkloop.h> +#include <Ivy/ivy.h> +#include <Ivy/ivyglibloop.h> #include <stdio.h> #include <stdlib.h> |