From 1f28a586dfc64b7c021eb3e3894a72b4b84482af Mon Sep 17 00:00:00 2001 From: jacomi Date: Tue, 30 Mar 1999 12:59:36 +0000 Subject: *** empty log message *** --- doc/ivy-c-functions.1 | 280 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/ivy-c.1 | 218 +++------------------------------------ doc/ivy-c.htm | 228 +++------------------------------------- 3 files changed, 313 insertions(+), 413 deletions(-) create mode 100644 doc/ivy-c-functions.1 (limited to 'doc') diff --git a/doc/ivy-c-functions.1 b/doc/ivy-c-functions.1 new file mode 100644 index 0000000..4912340 --- /dev/null +++ b/doc/ivy-c-functions.1 @@ -0,0 +1,280 @@ +'\" +'\" 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-3.0 1 3.0 "Ivy-c-3.0 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 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* +\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 +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. +.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 +\fBIvyChannelSetUp\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: +\fBIvyChannelSetUp (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 */ + IvyChannelSetUp(0, NULL, NULL, HandleStdin); +/* starting the connection */ + IvyStart (bus); +/* Main loop */ + IvyMainLoop(0); +}; +.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.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 + diff --git a/doc/ivy-c.1 b/doc/ivy-c.1 index 4912340..14aed08 100644 --- a/doc/ivy-c.1 +++ b/doc/ivy-c.1 @@ -42,216 +42,29 @@ '\" # BS - start boxed text '\" # ^y = starting y location '\" # ^b = 1 -.TH Ivy-c-3.0 1 3.0 "Ivy-c-3.0 Library Functions" +.TH Ivy-c-3.0 1 3.0 "Ivy-c-3.0 Interface" .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, +ivy-c - a software bus library .SH SYNOPSIS -useful set of library functions for communicating between different +Ivy-c provides a useful set of C 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* -\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 -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. -.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 -\fBIvyChannelSetUp\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: -\fBIvyChannelSetUp (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. +Ivy is a software bus, ie a system that allows any software component to freely exchange data. +The basic principle of a software bus is to ease the rapid implementation of new agents, and to manage a dynamic collection of agents on the bus: agents connect, send and receive messages, and disconnect without perturbing the overall functionment of the bus. 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 */ - IvyChannelSetUp(0, NULL, NULL, HandleStdin); -/* starting the connection */ - IvyStart (bus); -/* Main loop */ - IvyMainLoop(0); -}; -.DE +The essential functions of Ivy are: +.nf +.I Connexion +.nf +.I Message sending +.nf +.I Message subscription +.nf +.I Main loop .SH FILES .I /usr/include/ivy.h @@ -268,10 +81,13 @@ error messages displayed .SH BUGS none reported yet! .SH AUTHORS +.nf Francois-Regis Colin +.nf Stephane Chatty .SH SEE ALSO ivyprobe (1) +ivy-c-functions (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 diff --git a/doc/ivy-c.htm b/doc/ivy-c.htm index 8256c39..067350a 100644 --- a/doc/ivy-c.htm +++ b/doc/ivy-c.htm @@ -1,5 +1,6 @@ +c - a software bus library @@ -15,227 +16,27 @@

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, +ivy-c - a software bus library

SYNOPSIS

-useful set of library functions for communicating between different +Ivy-c provides a useful set of C library functions for communicating between different processes through a software bus -
-

-IvyInit(AppName, ready, callback, data, die_callback, die_data) -

-void -IvyStart(bus) -

-void -IvyStop() -

-MsgRcvPtr -IvyBindMsg(callback, user_data, regexp, ...) -

-void -IvyUnbindMsg(id) -

-void -IvyBindDirectMsg(callback, user_data) -

-int -IvySendMsg(fmt_message, ...) -

-void -IvySendDirectMsg(app, id, msg) -

-void -IvySendDieMsg(app) -

-void -IvySendError(app, id, fmt, ...) -

-char* -IvyGetApplicationName(app) -

-char* -IvyGetApplicationHost(app) -

-char* -IvyGetApplication(name) -

-char* -IvyGetApplicationList() -

-char** -IvyGetApplicationMessages(\fapp) -

-char* -IvyDefaultApplicationCallback(app, user_data, Event) -char* -IvyClasses(argc, argv) -

-void -IvyChannelInit(void) -

-Channel -IvyChannelSetUp(fd, data, handle_delete, handle_read) -

-void -IvyMainLoop(hook) -

-void -IvyChannelClose(channel) -

-static void -IvyChannelDelete(channel) -

-static void -IvyChannelHandleRead(current) -

-static void -IvyChannelHandleExcpt(current) -

-static void -IvyXtChannelInit(void) -

-static void -IvyXtChannelSetUp(fd, data, handle_delete, handle_read) -

-void -IvyXtChannelClose(channel) -

-static void -IvyXtHandleChannelRead(closure, source, id) -

-static void -IvyXtHandleChannelDelete(closure, source, id) -

-void -IvyChannelAppContext(cntx) -

ARGUMENTS

-Only main functions are detailed in this section -

-IvyInit: -Initialisation of a connection -

-

-
const_char *AppName -(in)
Application Name -
const_char *ready -(in)
Ready Message (can be NULL) -
IvyApplicationCallback callback -(in)
Callback to be called on a connexion/deconnexion of an application -
void *data -(in)
user data -
IvyDieCallback die_callback -(in)
last change callback before die -
void *die_data -(in)
user data -
-

Example:

-IvyInit ("PLN-SERVER", "PLN-READY", NULL, NULL, NULL); -

-IvyStart: -Initialisation of TCP/UPD port and sending of a broadcast handshake on every network -
-
const_char *bus -(in)
Bus to be used (format : network list followed by broadcast port). -
-

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 -IVYBUS is checked, else the default value : 127.255.255.255:2010 -is used (broadcast on the local machine). -
-IvyStart ("143.196.53.255:2001"); -

-IvyBindMsg: -Message binding -
-
MsgCallback callback -(in)
void *user_data -(in)
const_char *regexp -(in)
MsgRcvPtr id -(out)
-

Example:

-IvyBindMsg (StartTimeCallback, 0, "^CLOCK Start time=(.*)"); -
-In this example the function StartTimeCallback will be called -each time the string CLOCK Start time=(.*) will be emitted on -the bus. -

-IvyUnbindMsg: -Message unbinding -
-
MsgRcvPtr id -(in)
ident of the message to unbind -
-

-IvySendMsg: -Sending a message -
-
const_char* fmt -(in)
String to be sent on the bus -
-

Example:

-IvySendMsg ("SECTOR:%s.AIRCRAFT:%s Entered", sectorname, pln->indicatif); -

-IvyChannelSetUp: -
-
HANDLE fd -(in)
void *data -(in)
ChannelHandleDelete handle_delete -(in)
ChannelHandleRead handle_read -(in)
Channel out -(out)
-

Example:

-IvyChannelSetUp (0, NULL, NULL, HandleStdin);: -
-

DESCRIPTION

-

-These functions provide facilities for connecting applications on a -software bus and managing messages exchanges among them. +Ivy is a software bus, ie a system that allows any software component to freely exchange data. +The basic principle of a software bus is to ease the rapid implementation of new agents, and to manage a dynamic collection of agents on the bus: agents connect, send and receive messages, and disconnect without perturbing the overall functionment of the bus. 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. - -

EXAMPLE

-Connection of the application IVYPROBE on a given bus
- +The essential functions of Ivy are:
-
-
-#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 */
-	IvyChannelSetUp(0, NULL, NULL, HandleStdin);
-/* starting the connection */
-	IvyStart (bus);
-/* Main loop */
-	IvyMainLoop(0);
-};
+Connexion
+

+Message
+

+Message
 

-
+Main

FILES

/usr/include/ivy.h @@ -252,10 +53,13 @@ error messages displayed

BUGS

none reported yet!

AUTHORS

+
Francois-Regis Colin <fcolin@cenatoulouse.dgac.fr> +
Stephane Chatty <chatty@cenatoulouse.dgac.fr> -

SEE ALSO

+

SEE ALSO

ivyprobe (1) +ivy-c-functions (1)

For further details, please refer to the Ivy html page at http://www.cenatls.cena.dgac.fr/pii/produits/Ivy.html

NOTES

-- cgit v1.1