path: root/xpa/man/man3/xpanew.3

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "xpanew 3"
.TH xpanew 3 "July 23, 2013" "version 2.1.15" "SAORD Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
\&\fBXPANew: create a new \s-1XPA\s0 access point\fR
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  #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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Create a new \s-1XPA\s0 public access point with the class:name
identifier template
and enter this access point into the \s-1XPA\s0 name server, so that it
can be accessed by external processes. \fIXPANew()\fR returns an \s-1XPA\s0 struct.
Note that the length of the class and name designations must be less
than or equal to 1024 characters each.
.PP
The \s-1XPA\s0 name server daemon, xpans, will be started automatically if it
is not running already (assuming it can be found in the path).  The
program's ip address and listening port are specified by the
environment variable \s-1XPA_NSINET\s0, which takes the form :.  If
no such environment variable exists, then xpans is started on the
current machine listening on port 14285.  It also uses 14286 as a
known port for its public access point (so that routines do not have
to go to the name server to find the name server ip and port!)
As of \s-1XPA\s0 2.1.1, version information is exchanged between the xpans
process and the new access point. If the access point uses an \s-1XPA\s0
major/minor version newer than xpans, a warning is issued by both processes,
since mixing of new servers and old xpa programs (xpaset, xpaget,
xpans, etc.) is not likely to work. You can turn off the warning
message by setting the \s-1XPA_VERSIONCHECK\s0 environment variable to \*(L"false\*(R".
.PP
The help string is meant to be returned by a request from xpaget:
.PP
.Vb 1
\&  xpaget class:name \-help
.Ve
.PP
A send_callback and/or a receive_callback can be specified; at
least one of them must be specified.
.PP
A send_callback can be specified that will be executed in response to
an external request from the xpaget program, the \fIXPAGet()\fR routine, or
\&\fIXPAGetFd()\fR routine. This callback is used to send data to the
requesting client.
.PP
The calling sequence for \fIsend_callback()\fR is:
.PP
.Vb 7
\&  int send_callback(void *send_data, void *call_data,
\&    char *paramlist, char **buf, size_t *len)
\&  {
\&    XPA xpa = (XPA)call_data;
\&    ...
\&    return(stat);
\&  }
.Ve
.PP
The send_mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R"
The following keywords are recognized:
.PP
.Vb 4
\&  key           value           default         explanation
\&  \-\-\-\-\-\-        \-\-\-\-\-\-\-\-        \-\-\-\-\-\-\-\-        \-\-\-\-\-\-\-\-\-\-\-
\&  acl           true/false      true            enable access control
\&  freebuf       true/false      true            free buf after callback completes
.Ve
.PP
The call_data should be recast to the \s-1XPA\s0 struct as shown.  In
addition, client-specific data can be passed to the callback in
send_data.
.PP
The paramlist will be supplied by the client as qualifying parameters
for the callback.  There are two ways in which the \fIsend_callback()\fR
routine can send data back to the client:
.PP
1. The \fIsend_callback()\fR routine can fill in a buffer and pass back a
pointer to this buffer. An integer len also is returned to specify the
number of bytes of data in buf.  \s-1XPA\s0 will send this buffer to the
client after the callback is complete.
.PP
2. The send_callback can send data directly to the client by writing
to the fd pointed by the macro:
.PP
.Vb 1
\&  xpa_datafd(xpa)
.Ve
.PP
Note that this fd is of the kind returned by \fIsocket()\fR or \fIopen()\fR.
.PP
If a buf has been allocated by a standard malloc routine, filled, and
returned to \s-1XPA\s0, then freebuf generally is set so that the buffer will
be freed automatically when the callback is completed and data has
been sent to the client.  If a static buf is returned, freebuf should
be set to false to avoid a system error when freeing static storage.
Note that default value for freebuf implies that the callback will
allocate a buffer rather than use static storage.
.PP
On the other hand, if buf is dynamically allocated using a method
other than a standard malloc/calloc/realloc routine (e.g. using Perl's
memory allocation and garbage collection scheme), then it is necessary
to tell \s-1XPA\s0 how to free the allocated buffer. To do this, use the
\&\fIXPASetFree()\fR routine within your callback:
.PP
.Vb 1
\&  void XPASetFree(XPA xpa, void (*myfree)(void *), void *myfree_ptr);
.Ve
.PP
The first argument is the usual \s-1XPA\s0 handle. The second argument is the
special routine to call to free your allocated memory. The third
argument is an optional pointer.  If not \s-1NULL\s0, the specified free
routine is called with that pointer as its sole argument. If \s-1NULL\s0, the
free routine is called with the standard buf pointer as its sole
argument. This is useful in cases where there is a mapping between the
buffer pointer and the actual allocated memory location, and the
special routine is expecting to be passed the former.
.PP
If, while the callback performs its processing, an error occurs that
should be communicated to the client, then the routine XPAError should be
called:
.PP
.Vb 1
\&  XPAError(XPA xpa, char *s);
.Ve
.PP
where s is an arbitrary error message.  The returned error message
string will be of the form:
.PP
.Vb 1
\&  XPA$ERROR   [error] (class:name ip:port)
.Ve
.PP
If the callback wants to send a specific acknowledgment message back
to the client, the routine XPAMessage can be called:
.PP
.Vb 1
\&  XPAMessage(XPA xpa, char *s);
.Ve
.PP
where s is an arbitrary error message.  The returned error message
string will be of the form:
.PP
.Vb 1
\&  XPA$MESSAGE [message] (class:name ip:port)
.Ve
.PP
Otherwise, a standard acknowledgment is sent back to the client
after the callback is completed.
.PP
The callback routine should return 0 if no error occurs, or \-1 to
signal an error.
.PP
A receive_callback can be specified that will be executed in response
to an external request from the xpaset program, or the XPASet (or
\&\fIXPASetFd()\fR) routine. This callback is used to process data received
from an external process.
.PP
The calling sequence for receive_callback is:
.PP
.Vb 7
\&  int receive_callback(void *receive_data, void *call_data,
\&    char *paramlist, char *buf, size_t len)
\&  {
\&    XPA xpa = (XPA)call_data;
\&    ...
\&    return(stat);
\&  }
.Ve
.PP
The mode string is of the form: \*(L"key1=value1,key2=value2,...\*(R"
The following keywords are recognized:
.PP
.Vb 6
\&  key           value           default         explanation
\&  \-\-\-\-\-\-        \-\-\-\-\-\-\-\-        \-\-\-\-\-\-\-\-        \-\-\-\-\-\-\-\-\-\-\-
\&  acl           true/false      true            enable access control
\&  buf           true/false      true            server expects data bytes from client
\&  fillbuf       true/false      true            read data into buf before executing callback
\&  freebuf       true/false      true            free buf after callback completes
.Ve
.PP
The call_data should be recast to the \s-1XPA\s0 struct as shown.  In
addition, client-specific data can be passed to the callback in
receive_data.
.PP
The paramlist will be supplied by the client. In addition, if the
receive_mode keywords buf and fillbuf are true, then on entry into the
\&\fIreceive_callback()\fR routine, buf will contain the data sent by the
client. If buf is true but fillbuf is false, it becomes the callback's
responsibility to retrieve the data from the client, using the data fd
pointed to by the macro xpa_datafd(xpa).  If freebuf is true, then buf
will be freed when the callback is complete.
.PP
If, while the callback is performing its processing, an error occurs
that should be communicated to the client, then the routine XPAError
can be called:
.PP
.Vb 1
\&  XPAError(XPA xpa, char *s);
.Ve
.PP
where s is an arbitrary error message.
.PP
The callback routine should return 0 if no error occurs, or \-1 to
signal an error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See xpa(n) for a list of \s-1XPA\s0 help pages