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 IvyInit. 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 IvyStart. 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.
-
The Ivy C library provides its own main loop: IvyMainLoop. 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 IvyMainLoop. From within the main loop, you can call IvyStop to
-exit the loop.
-
Here are more details on those functions: -
-
-
-void IvyInit (const char* agentname,
- const char* hello_msg,
- IvyApplicationCallback app_cb,
- void *app_data,
- IvyDieCallback die_cb,
- void *die_data);
-
--
-
-void IvyStart (const char* bus);
-
-bus. The string provided
-should follow the convention described in section XX. Example: "127:2010".
--
-
-void IvyMainLoop (void (*hook) (void));
-
--
-
-void IvyStop ();
-
--
-
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 IvySendMsg, which works like printf:
-
-
-
-void IvySendMsg (const char* format, ...);
-
-printf, sprintf or fprintf.
--
-
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 main. Use function IvyBindMsg
-to bind a callback to a pattern, and function IvyUnbindMsg to delete the
-binding.
-
-
-MsgRcvPtr IvyBindMsg (MsgCallback cb,
- void* data,
- const char* regex_format, ...);
-
-cb to the regular expression specified by
-regex_format and the optional following arguments. regex_format and
-the following arguments are handled as in printf.
--
-
-void IvyUnbindMsg (MsgRcvPtr id);
-
-id
--
In what precedes, MsgRcvPtr is an opaque type used to identify bindings,
-data is a user pointer passed to the callback whenever it is called, and
-Msgcallback is defined as follows:
-
-
-typedef void (*MsgCallback)(IvyClientPtr app, void *data, int argc, char **argv);
-
--
-
The following application connects to an Ivy bus, translates messages "Hi
-[name]" to "Bonjour [name]", and quits on message "Bye".
-
-
-#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);
-}
-
--
-
-
-