From f6432ffb2bd80a195563e8d93a6ffbb8cf022878 Mon Sep 17 00:00:00 2001 From: jestin Date: Thu, 20 Jul 2006 14:19:02 +0000 Subject: Documentation update 3.2 -> 3.8, mentionning: - include is now in Ivy/ivy.h - we now use PCRE - IvyMainLoop() now has two arguments - it's glib, and not gtk --- doc/ivy-c.sgml | 62 +++++++++++++++++++++++++++------------------------------- 1 file changed, 29 insertions(+), 33 deletions(-) (limited to 'doc/ivy-c.sgml') 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 @@ December 11, 2002 -1998-2002 +1998-2006 Centre d'Études de la Navigation Aérienne 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. @@ -90,7 +90,7 @@ library, please refer to The Ivy sofware bus: a white paper. If you want more details about the internals of Ivy, have a look at The Ivy architecture and protocol. And finally, if you are more interested in other languages, refer to other guides such as -The Ivy Perl library guide. All those documents should be +The Ivy Java library guide. All those documents should be available from the Ivy Web site at http://www.tls.cena.fr/products/ivy/. @@ -108,7 +108,7 @@ Ivy bus. This guide is here to help you do that. -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. @@ -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 (http://www.tls.cena.fr/products/ivy/). 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. @@ -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); } @@ -308,14 +308,15 @@ environment variable is not defined, the default value "127:2010" is used. -void IvyMainLoop (void (*hook) (void)); +void IvyMainLoop (void (*beforehook) (void),void (*afterhook) (void)); 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 select POSIX system call. -If non-null, hook is called every time the main loop is +If non-null, beforehook is called every time the main loop is about to enter select, and can be used (with care!) to -extend the main loop. +extend the main loop. afterhook is called each time the +main loop exits select. void IvyStop (); @@ -346,7 +347,9 @@ sends a message on the bus. This function has exactly the same behaviour as Subscribing to messages 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 Perl Compatible Regular +Expression. 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) Direct messages -[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. @@ -587,21 +593,11 @@ int main(int argc,char *argv[]){ Using Ivy with Tcl/Tk -Just load the libtclivy.so package, and use the following commands - -#!/usr/bin/tclsh -Ivy::init $name $hellomessge connectproc dieproc -Ivy::start $domain -Ivy::bind $regexp ballback -Ivy::applist -Ivy::send $message -Ivy::applist -mainloop - + A full example in Tcl/Tk is provided here: #!/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 -Using Ivy with Gtk +Using Ivy with Gtk/Gdk There is little to do to make your gtk applications Ivy aware: just add the following lines into your code: -#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); 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 . #include <gtk/gtk.h> -#include <ivy.h> -#include <ivygtkloop.h> +#include <Ivy/ivy.h> +#include <Ivy/ivyglibloop.h> #include <stdio.h> #include <stdlib.h> -- cgit v1.1