'\"
'\" Ivy, C interface \- library managing connexions to a software bus
'\"
'\" Copyright (C) 1997-1999
'\" 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 1 3.0  "Ivy-c Library Functions"
.SH NAME
IvyInit, IvyStart, IvyStop, IvyBindMsg, IvyUnbindMsg, IvyBindDirectMsg,
IvySendMsg, IvySendDirectMsg, IvySendDieMsg, IvySendError, IvyGetApplicationName,
IvyGetApplicationHost, IvyGetApplication, IvyGetApplicationList,
IvyGetApplicationMessages, IvyDefaultApplicationCallback, IvyClasses,
IvyChannelInit, IvyChannelSetUp, IvyMainLoop, IvyChannelClose,
IvyChannelDelete, IvyChannelHandleRead,
IvyChannelHandleExcpt,  IvyXtChannelInit, IvyXtChannelSetUp
IvyXtChannelClose, IvyXtHandleChannelRead, IvyXtHandleChannelDelete,
IvyXtChannelAppContext, 
.SH SYNOPSIS
useful library functions for communicating through a sofware 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*
\fBIvyClasses(\fIargc, argv\fB)\fR
.sp
void
\fBIvyChannelInit(\fIvoid\fB)\fR
.sp
Channel
\fBIvyChannelSetUp(\fIfd, data, handle_delete, handle_read\fB)\fR
.sp
void
\fBIvyMainLoop(\fIhook\fB)\fR
.sp
void
\fBIvyChannelClose(\fIchannel\fB)\fR
.sp
static void
\fBIvyChannelDelete(\fIchannel\fB)\fR
.sp
static void
\fBIvyChannelHandleRead(\fIcurrent\fB)\fR
.sp
static void
\fBIvyChannelHandleExcpt(\fIcurrent\fB)\fR
.sp
static void
\fBIvyXtChannelInit(\fIvoid\fB)\fR
.sp
static void
\fBIvyXtChannelSetUp(\fIfd, data, handle_delete, handle_read\fB)\fR
.sp
void
\fBIvyXtChannelClose(\fIchannel\fB)\fR
.sp
static void
\fBIvyXtHandleChannelRead(\fIclosure, source, id\fB)\fR
.sp
static void
\fBIvyXtHandleChannelDelete(\fIclosure, source, id\fB)\fR
.sp
void
\fBIvyChannelAppContext(\fIcntx\fB)\fR
.SH ARGUMENTS
.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
\fBIvyStart\fR:
Initialisation of TCP/UPD port and sending of a broadcast handshake on every network
.AP const_char *bus in
Bus (format : network list followed by broadcast port) example :
123.231,123.123:2000 or 123.231 or :2000
If no argument specified, check the environment variable \fBIVYBUS\fR, 
else use the default value : 127.255.255.255:2010
.SH 
\fBIvyBindMsg\fR:
Message binding
.AP MsgCallback callback in
.AP void *user_data in
.AP const_char *regexp in
.AP MsgRcvPtr id out
.SH 
\fBIvyUnbindMsg\fR:
Message unbinding
.AP MsgRcvPtr id in
.SH
\fBIvyChannelSetUp\fR:

.AP HANDLE fd in
.AP void *data in
.AP ChannelHandleDelete handle_delete in
.AP ChannelHandleRead handle_read in
.AP Channel out out
.VE 
.BE
.SH DESCRIPTION
.PP
These procedures provide facilities for connecting applications on a
software bus and managing messages exchanges among them.

.SH EXAMPLES
Simple C code:
.nf

.DS

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

 int main (int argc, char* argv[]){
	IvyInit ("IVYPROBE",
		 bport,
		 "IVYPROBE READY",
		 ApplicationCallback,
		 NULL,
		 NULL,
		 NULL)
	IvyChannelSetUp(0, NULL, NULL, HandleStdin);
	IvyStart (domains);
	IvyMainLoop(0)
};
.DE

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