diff options
Diffstat (limited to 'doc/ivy-c-3.html')
| -rw-r--r-- | doc/ivy-c-3.html | 199 |
1 files changed, 199 insertions, 0 deletions
diff --git a/doc/ivy-c-3.html b/doc/ivy-c-3.html new file mode 100644 index 0000000..8ff844c --- /dev/null +++ b/doc/ivy-c-3.html @@ -0,0 +1,199 @@ +<!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-c-4.html" REL=next> + <LINK HREF="ivy-c-2.html" REL=previous> + <LINK HREF="ivy-c.html#toc3" REL=contents> +</HEAD> +<BODY> +<A HREF="ivy-c-4.html">Next</A> +<A HREF="ivy-c-2.html">Previous</A> +<A HREF="ivy-c.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 C library is a two step process. First of +all, you should initialize the library by calling function <CODE>IvyInit</CODE>. Once +the library is initialized you can create timers and add subscriptions, but your +agent is still not connected to any bus. In order to connect, you should call +function <CODE>IvyStart</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 C library provides its own main loop: <CODE>IvyMainLoop</CODE>. You should use +it unless you already use a toolkit that provides its own main loop and you want +to use that one. If it is the case, please refer to section XX. Otherwise, just +call <CODE>IvyMainLoop</CODE>. From within the main loop, you can call <CODE>IvyStop</CODE> to +exit the loop. +<P>Here are more details on those functions: +<P> +<BLOCKQUOTE><CODE> +<PRE> +void IvyInit (const char* agentname, + const char* hello_msg, + IvyApplicationCallback app_cb, + void *app_data, + IvyDieCallback die_cb, + void *die_data); +</PRE> +</CODE></BLOCKQUOTE> + +initializes the library. blahblah +<P> +<BLOCKQUOTE><CODE> +<PRE> +void IvyStart (const char* bus); +</PRE> +</CODE></BLOCKQUOTE> + +connects your application to the bus specified in <CODE>bus</CODE>. The string provided +should follow the convention described in section XX. Example: <CODE>"127:2010"</CODE>. +<P> +<BLOCKQUOTE><CODE> +<PRE> +void IvyMainLoop (void (*hook) (void)); +</PRE> +</CODE></BLOCKQUOTE> + +makes your application enter the main loop in which it will handle asynchronous +communications and signals. +<P> +<BLOCKQUOTE><CODE> +<PRE> +void IvyStop (); +</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> +void IvySendMsg (const char* format, ...); +</PRE> +</CODE></BLOCKQUOTE> + +sends a message on the bus. This function has exactly the same behaviour as +<CODE>printf</CODE>, <CODE>sprintf</CODE> or <CODE>fprintf</CODE>. +<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>IvyBindMsg</CODE> +to bind a callback to a pattern, and function <CODE>IvyUnbindMsg</CODE> to delete the +binding. +<BLOCKQUOTE><CODE> +<PRE> +MsgRcvPtr IvyBindMsg (MsgCallback cb, + void* data, + const char* regex_format, ...); +</PRE> +</CODE></BLOCKQUOTE> + +binds callback function <CODE>cb</CODE> to the regular expression specified by +<CODE>regex_format</CODE> and the optional following arguments. <CODE>regex_format</CODE> and +the following arguments are handled as in <CODE>printf</CODE>. +<P> +<BLOCKQUOTE><CODE> +<PRE> +void IvyUnbindMsg (MsgRcvPtr id); +</PRE> +</CODE></BLOCKQUOTE> + +deletes the binding specified by <CODE>id</CODE> +<P> +<P>In what precedes, <CODE>MsgRcvPtr</CODE> is an opaque type used to identify bindings, +<CODE>data</CODE> is a user pointer passed to the callback whenever it is called, and +<CODE>Msgcallback</CODE> is defined as follows: +<BLOCKQUOTE><CODE> +<PRE> +typedef void (*MsgCallback)(IvyClientPtr app, void *data, int argc, char **argv); +</PRE> +</CODE></BLOCKQUOTE> +<P> +<P> +<H2><A NAME="ss3.4">3.4 Example</A> +</H2> + +<P>The following application connects to an Ivy bus, translates messages <CODE>"Hi +[name]"</CODE> to <CODE>"Bonjour [name]"</CODE>, and quits on message <CODE>"Bye"</CODE>. +<BLOCKQUOTE><CODE> +<PRE> +#include <stdlib.h> +#include <stdio.h> +#include <getopt.h> +#include <ivy.h> +#include <ivyloop.h> + +/* callback associated to "Hi" messages */ +void HiCallback (IvyClientPtr app, void *data, int argc, char **argv) +{ + if (argc != 1) + fprintf (stderr, "wrong format!\n"); + else + IvySendMsg ("Bonjour %s", argv[0]); +} + +void ByeCallback (IvyClientPtr app, void *data, int argc, char **argv) +{ + IvyStop (); +} + +main (int argc, char**argv) +{ + /* handling of -b option */ + const char* bus = 0; + char c; + while (c = getopt (argc, argv, "b:") != EOF) { + switch (c) { + case 'b': + bus = optarg; + break; + } + } + + /* handling of environment variable */ + if (!bus) + bus = getenv ("IVYBUS"); + + /* initializations */ + IvyInit ("MagicTranslater", "Hello le monde", 0, 0, 0, 0); + IvyStart (bus); + + /* bindings */ + IvyBindMsg (HiCallback, 0, "^Hi (.*)"); + IvyBindMsg (ByeCallback, 0, "^Bye$"); + + /* main loop */ + IvyMainLoop (0); +} +</PRE> +</CODE></BLOCKQUOTE> +<P> +<P> +<P> +<P> +<HR> +<A HREF="ivy-c-4.html">Next</A> +<A HREF="ivy-c-2.html">Previous</A> +<A HREF="ivy-c.html#toc3">Contents</A> +</BODY> +</HTML> |