xpaserver(3) [debian man page]

xpaserver(3)							SAORD Documentation						      xpaserver(3)

NAME

       XPAServer -  The XPA Server-side Programming Interface

SYNOPSIS

       A description of the XPA server-side programming interface.

DESCRIPTION

       Introduction to XPA Server Programming

       Creating an XPA server is easy: you generally only need to call the XPANew() subroutine to define a named XPA access point and set up the
       send and receive callback routines.  You then enter an event loop such as XPAMainLoop() to field XPA requests.

	 #include <xpa.h>

	 XPA XPANew(char *class, char *name, char *help,
	     int (*send_callback)(), void *send_data, char *send_mode,
	     int (*rec_callback)(),  void *rec_data,  char *rec_mode);

	 XPA XPACmdNew(char *class, char *name);

	 XPACmd XPACmdAdd(XPA xpa,
		char *name, char *help,
		int (*send_callback)(), void *send_data, char *send_mode,
		int (*rec_callback)(),	void *rec_data,  char *rec_mode);

	 void XPACmdDel(XPA xpa, XPACmd cmd);

	 XPA XPAInfoNew(char *class, char *name,
	     int (*info_callback)(), void *info_data, char *info_mode);

	 int XPAFree(XPA xpa);

	 void XPAMainLoop(void);

	 int XPAPoll(int msec, int maxreq);

	 void XPAAtExit(void);

	 void XPACleanup(void);

       Introduction

       To use the XPA application programming interface, a software developer generally will include the xpa.h definitions file:

	 #include <xpa.h>

       in the software module that defines or accesses an XPA access point, and then will link against the libxpa.a library:

	 gcc -o foo foo.c libxpa.a

       XPA has been compiled using both C and C++ compilers.

       A server program generally defines an XPA access point by calling the XPANew() routine and specifies "send" and/or "receive" callback pro-
       cedures to be executed by the program when an external process either sends data or commands to this access point or requests data or
       information from this access point. A program also can define several sub-commands for a single access point by calling XPACmdNew() and
       XPACmdAdd() instead.  Having defined one or more public access points in this way, an XPA server program enters its usual event loop (or
       uses the standard XPA event loop).

SEE ALSO

       See xpa(7) for a list of XPA help pages

version 2.1.14							   June 7, 2012 						      xpaserver(3)

xpamainloop(3)							SAORD Documentation						    xpamainloop(3)

NAME

       XPAMainLoop -  optional main loop for XPA

SYNOPSIS

	 #include <xpa.h>

	 void XPAMainLoop();

DESCRIPTION

       Once XPA access points have been defined, a program must enter an event loop to watch for requests from external programs. This can be done
       in a variety of ways, depending on whether the event loop is processing events other than XPA events.  In cases where there are no non-XPA
       events to be processed, the program can simply call the XPAMainLoop() event loop.  This loop is implemented essentially as follows (error
       checking is simplified in this example):

	 FD_ZERO(&readfds);
	 while( XPAAddSelect(NULL, &readfds) ){
	   if( sgot = select(swidth, &readfds, NULL, NULL, NULL) >0 )
	     XPAProcessSelect(&readfds, 0);
	   else
	     break;
	   FD_ZERO(&readfds);
	 }

       The XPAAddSelect() routine sets up the select() readfds variable so that select() will wait for I/O on all the active XPA channels.  It
       returns the number of XPAs that are active; the loop will end when there are no active XPAs. The standard select() routine is called to
       wait for an external I/O request.  Since no timeout struct is passed in argument 5, the select() call hangs until there is an external
       request.  When an external I/O request is made, the XPAProcessSelect() routine is executed to process the pending requests.  In this rou-
       tine, the maxreq value determines how many requests will be processed: if maxreq <=0, then all currently pending requests will be pro-
       cessed.	Otherwise, up to maxreq requests will be processed.  (The most usual values for maxreq is 0 to process all requests.)

       If a program has its own Unix select() loop, then XPA access points can be added to it by using a variation of the standard XPAMainLoop:

	 XPAAddSelect(xpa, &readfds);
	 [app-specific ...]
	 if( select(width, &readfds, ...) ){
	   XPAProcessSelect(&readfds, maxreq);
	   [app-specific ...]
	   FD_ZERO(&readfds);
	 }

       XPAAddSelect() is called before select() to add the access points.  If the first argument is NULL, then all active XPA access points are
       added. Otherwise only the specified access point is added.  After select() is called, the XPAProcessSelect() routine can be called to
       process XPA requests.  Once again, the maxreq value determines how many requests will be processed: if maxreq <=0, then all currently pend-
       ing requests will be processed.	Otherwise, up to maxreq requests will be processed.

       XPA access points can be added to Xt event loops (using XtAppMainLoop()) and Tcl/Tk event loops (using vwait and the Tk loop).  When using
       XPA with these event loops, you only need to call:

       int XPAXtAddInput(XtAppContext app, XPA xpa)

       or

	 int XPATclAddInput(XPA xpa)

       respectively before entering the loop.

SEE ALSO

       See xpa(7) for a list of XPA help pages

version 2.1.14							   June 7, 2012 						    xpamainloop(3)