'\"
'\" Ivy, C interface \- library managing connexions to a software bus
'\"
'\" Copyright (C) 1997-2006
'\" Centre d'Études de la Navigation Aérienne
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" 
'\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ie !"\\$3"" \{\
.ta \\n()Au \\n()Bu
\&\\$1	\\fI\\$2\\fP	(\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
'\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
'\"	# BS - start boxed text
'\"	# ^y = starting y location
'\"	# ^b = 1
.TH Ivy-c-3.9 1 3.9  "Ivy-c-3.9 Library Functions"
.SH NAME
IvyInit, IvyStart, IvyStop, IvyBindMsg, IvyUnbindMsg, IvyBindDirectMsg,
IvySendMsg, IvySendDirectMsg, IvySendDieMsg, IvySendError, IvyGetApplicationName,
IvyGetApplicationHost, IvyGetApplication, IvyGetApplicationList,
IvyGetApplicationMessages, IvyDefaultApplicationCallback, IvySetFilter, IvySetBindCallback,
IvyChannelInit, IvyChannelStop, IvyChannelAdd, IvyChannelRemove, IvyMainLoop,
IvyChannelDelete, IvyChannelHandleRead, IvyChannelHandleExcpt,
IvySetBeforeSelectHook, IvySetAfterSelectHook,
IvyXtChannelAppContext, 
.SH SYNOPSIS
useful set of library functions for communicating between different
processes through a software bus
.nf
.sp
\fBIvyInit(\fIAppName, ready, callback, data, die_callback, die_data\fB)\fR
.sp
void
\fBIvyStart(\fIbus\fB)\fR
.sp
void
\fBIvyStop()\fR
.sp
MsgRcvPtr
\fBIvyBindMsg(\fIcallback, user_data, regexp, ...\fB)\fR
.sp
void
\fBIvyUnbindMsg(\fIid\fB)\fR
.sp
void
\fBIvyBindDirectMsg(\fIcallback, user_data\fB)\fR
.sp
int
\fBIvySendMsg(\fIfmt_message, ...\fB)\fR
.sp
void
\fBIvySendDirectMsg(\fIapp, id, msg\fB)\fR
.sp
void
\fBIvySendDieMsg(\fIapp\fB)\fR
.sp
void
\fBIvySendError(\fIapp, id, fmt, ...\fB)\fR
.sp
char*
\fBIvyGetApplicationName(\fIapp\fB)\fR
.sp
char*
\fBIvyGetApplicationHost(\fIapp\fB)\fR
.sp
char*
\fBIvyGetApplication(\fIname\fB)\fR
.sp
char*
\fBIvyGetApplicationList()\fR
.sp
char**
\fBIvyGetApplicationMessages(\fapp\fB)\fR
.sp
char*
\fBIvyDefaultApplicationCallback(\fIapp, user_data, Event\fB)\fR
char*
\fBIvySetFilter(\fIargc, argv\fB)\fR
.sp
void
\fBIvyChannelInit(\fIvoid\fB)\fR
.sp
Channel
\fBIvyChannelAdd(\fIfd, data, handle_delete, handle_read\fB)\fR
.sp
void
\fBIvyChannelRemove(\fIchannel\fB)\fR
.sp
void
\fBIvyMainLoop()\fR
.sp
static void
\fBIvyChannelHandleRead(\fIcurrent\fB)\fR
.sp
static void
\fBIvyChannelHandleExcpt(\fIcurrent\fB)\fR
.sp
void
\fBIvyXtChannelAppContext(\fIcntx\fB)\fR
.SH ARGUMENTS
Only main functions are detailed in this section
.SH
\fBIvyInit\fR:
Initialisation of a connection
.sp
.AS "MaxSize" die_callback
.AP const_char *AppName in
Application Name
.AP const_char *ready in
Ready Message (can be NULL)
.AP IvyApplicationCallback callback in
Callback to be called on a connexion/deconnexion of an application
.AP void *data in
user data 
.AP IvyDieCallback die_callback in
last change callback before die
.AP void *die_data in
user data
.SH Example:
\fBIvyInit ("PLN-SERVER", "PLN-READY", NULL, NULL, NULL);\fR
.SH
\fBIvyStart\fR:
Initialisation of TCP/UPD port and sending of a broadcast handshake on every network
.AP const_char *bus in
Bus to be used (format : network list followed by broadcast port).
.SH Example:
the given bus can be a string like 123.231,123.123:2000 or 123.231 or
:2000. If no argument is specified, then the environment variable
\fBIVYBUS\fR is checked, else the default value : 127.255.255.255:2010 
is used (broadcast on the local machine).
.nf
\fBIvyStart ("143.196.53.255:2001");\fR
.SH 
\fBIvyBindMsg\fR:
Message binding
.AP MsgCallback callback in
.AP void *user_data in
.AP const_char *regexp in
.AP MsgRcvPtr id out
.SH Example:
\fBIvyBindMsg (StartTimeCallback, 0,  "^CLOCK Start time=(.*)");\fR
.nf
In this example the function \fBStartTimeCallback\fR will be called
each time the string \fBCLOCK Start time=(.*)\fR will be emitted on
the bus.
There is a special syntax for specifying numeric interval, in this case
the interval is locally transformed in a pcre regexp.
syntax is \fB(?Imin#max[fi])\fR. min and max are the bounds,
by default the regexp match decimal number, but if max bound is
followed by 'i', the regexp match only integers ex : \fB(?I-10#20), (?I20#25i)\fR
Note that due to the regexp generator limitation (which will perhaps be raised eventually)
the bounds are always integers.
.SH 
\fBIvyUnbindMsg\fR:
Message unbinding
.AP MsgRcvPtr id in
ident of the message to unbind
.SH 
\fBIvySendMsg\fR:
Sending a message
.AP const_char* fmt in
String to be sent on the bus
.SH Example:
\fBIvySendMsg ("SECTOR:%s.AIRCRAFT:%s Entered", sectorname, pln->indicatif);\fR
.SH
\fBIvyChannelAdd\fR:
.AP HANDLE fd in
.AP void *data in
.AP ChannelHandleDelete handle_delete in
.AP ChannelHandleRead handle_read in
.AP Channel out out
.SH Example:
\fBIvyChannelAdd (0, NULL, NULL, HandleStdin);\fR:
.VE 
.BE
.SH DESCRIPTION
.PP
These functions provide facilities for connecting applications on a
software bus and managing messages exchanges among them.
Each time an application initializes a connection on the bus, a
"ready" message is sent to all other applications already connected, and the
list of the messages subscribed by this application is dispatched.
The format for the messages is free.

.SH EXAMPLE
Connection of the application \fBIVYPROBE\fR on a given bus
.nf

.DS

#include "ivyloop.h"
#include "ivysocket.h"
#include "ivy.h"

 int main (int argc, char* argv[]){
/* bus domain and port number to be used */
	const char* bus="127.255.255.255:2010";
/* initialisation of the connection */
	IvyInit ("IVYPROBE",
		 bport,
		 "IVYPROBE READY",
		 ApplicationCallback,
		 NULL,
		 NULL,
		 NULL);
/* keyboard's inputs management */
	IvyChannelAdd(0, NULL, NULL, HandleStdin);
/* starting the connection */
	IvyStart (bus);
/* Main loop */
	IvyMainLoop();
};
.DE

.SH FILES
.I /usr/include/ivy.h
.nf
.I /usr/include/ivyloop.h
.nf
.I /usr/include/ivysocket.h
.SH ENVIRONMENT
.I IVYBUS
.nf
.I IVYDOMAINS
.SH DIAGNOSTICS
error messages displayed
.SH BUGS
none reported yet!
.SH AUTHORS
Francois-Regis Colin
Stephane Chatty
.SH SEE ALSO
ivyprobe (1)
.sp
For further details, please refer to the Ivy html page at http://www.tls.cena.fr/pii/produits/Ivy.html
.SH NOTES
In case of any comment or bug report on this library, please contact
ivy@tls.cena.fr