1xpanew(3)                     SAORD Documentation                    xpanew(3)
2
3
4

NAME

6       XPANew: create a new XPA access point
7

SYNOPSIS

9         #include <xpa.h>
10
11         XPA XPANew(char *class, char *name, char *help,
12                    int (*send_callback)(),
13                    void *send_data, char *send_mode,
14                    int (*rec_callback)(),
15                    void *rec_data,  char *rec_mode);
16

DESCRIPTION

18       Create a new XPA public access point with the class:name identifier
19       template and enter this access point into the XPA name server, so that
20       it can be accessed by external processes. XPANew() returns an XPA
21       struct.  Note that the length of the class and name designations must
22       be less than or equal to 1024 characters each.
23
24       The XPA name server daemon, xpans, will be started automatically if it
25       is not running already (assuming it can be found in the path).  The
26       program's ip address and listening port are specified by the
27       environment variable XPA_NSINET, which takes the form :.  If no such
28       environment variable exists, then xpans is started on the current
29       machine listening on port 14285.  It also uses 14286 as a known port
30       for its public access point (so that routines do not have to go to the
31       name server to find the name server ip and port!)  As of XPA 2.1.1,
32       version information is exchanged between the xpans process and the new
33       access point. If the access point uses an XPA major/minor version newer
34       than xpans, a warning is issued by both processes, since mixing of new
35       servers and old xpa programs (xpaset, xpaget, xpans, etc.) is not
36       likely to work. You can turn off the warning message by setting the
37       XPA_VERSIONCHECK environment variable to "false".
38
39       The help string is meant to be returned by a request from xpaget:
40
41         xpaget class:name -help
42
43       A send_callback and/or a receive_callback can be specified; at least
44       one of them must be specified.
45
46       A send_callback can be specified that will be executed in response to
47       an external request from the xpaget program, the XPAGet() routine, or
48       XPAGetFd() routine. This callback is used to send data to the
49       requesting client.
50
51       The calling sequence for send_callback() is:
52
53         int send_callback(void *send_data, void *call_data,
54           char *paramlist, char **buf, size_t *len)
55         {
56           XPA xpa = (XPA)call_data;
57           ...
58           return(stat);
59         }
60
61       The send_mode string is of the form: "key1=value1,key2=value2,..."  The
62       following keywords are recognized:
63
64         key           value           default         explanation
65         ------        --------        --------        -----------
66         acl           true/false      true            enable access control
67         freebuf       true/false      true            free buf after callback completes
68
69       The call_data should be recast to the XPA struct as shown.  In
70       addition, client-specific data can be passed to the callback in
71       send_data.
72
73       The paramlist will be supplied by the client as qualifying parameters
74       for the callback.  There are two ways in which the send_callback()
75       routine can send data back to the client:
76
77       1. The send_callback() routine can fill in a buffer and pass back a
78       pointer to this buffer. An integer len also is returned to specify the
79       number of bytes of data in buf.  XPA will send this buffer to the
80       client after the callback is complete.
81
82       2. The send_callback can send data directly to the client by writing to
83       the fd pointed by the macro:
84
85         xpa_datafd(xpa)
86
87       Note that this fd is of the kind returned by socket() or open().
88
89       If a buf has been allocated by a standard malloc routine, filled, and
90       returned to XPA, then freebuf generally is set so that the buffer will
91       be freed automatically when the callback is completed and data has been
92       sent to the client.  If a static buf is returned, freebuf should be set
93       to false to avoid a system error when freeing static storage.  Note
94       that default value for freebuf implies that the callback will allocate
95       a buffer rather than use static storage.
96
97       On the other hand, if buf is dynamically allocated using a method other
98       than a standard malloc/calloc/realloc routine (e.g. using Perl's memory
99       allocation and garbage collection scheme), then it is necessary to tell
100       XPA how to free the allocated buffer. To do this, use the XPASetFree()
101       routine within your callback:
102
103         void XPASetFree(XPA xpa, void (*myfree)(void *), void *myfree_ptr);
104
105       The first argument is the usual XPA handle. The second argument is the
106       special routine to call to free your allocated memory. The third
107       argument is an optional pointer.  If not NULL, the specified free
108       routine is called with that pointer as its sole argument. If NULL, the
109       free routine is called with the standard buf pointer as its sole
110       argument. This is useful in cases where there is a mapping between the
111       buffer pointer and the actual allocated memory location, and the
112       special routine is expecting to be passed the former.
113
114       If, while the callback performs its processing, an error occurs that
115       should be communicated to the client, then the routine XPAError should
116       be called:
117
118         XPAError(XPA xpa, char *s);
119
120       where s is an arbitrary error message.  The returned error message
121       string will be of the form:
122
123         XPA$ERROR   [error] (class:name ip:port)
124
125       If the callback wants to send a specific acknowledgment message back to
126       the client, the routine XPAMessage can be called:
127
128         XPAMessage(XPA xpa, char *s);
129
130       where s is an arbitrary error message.  The returned error message
131       string will be of the form:
132
133         XPA$MESSAGE [message] (class:name ip:port)
134
135       Otherwise, a standard acknowledgment is sent back to the client after
136       the callback is completed.
137
138       The callback routine should return 0 if no error occurs, or -1 to
139       signal an error.
140
141       A receive_callback can be specified that will be executed in response
142       to an external request from the xpaset program, or the XPASet (or
143       XPASetFd()) routine. This callback is used to process data received
144       from an external process.
145
146       The calling sequence for receive_callback is:
147
148         int receive_callback(void *receive_data, void *call_data,
149           char *paramlist, char *buf, size_t len)
150         {
151           XPA xpa = (XPA)call_data;
152           ...
153           return(stat);
154         }
155
156       The mode string is of the form: "key1=value1,key2=value2,..."  The
157       following keywords are recognized:
158
159         key           value           default         explanation
160         ------        --------        --------        -----------
161         acl           true/false      true            enable access control
162         buf           true/false      true            server expects data bytes from client
163         fillbuf       true/false      true            read data into buf before executing callback
164         freebuf       true/false      true            free buf after callback completes
165
166       The call_data should be recast to the XPA struct as shown.  In
167       addition, client-specific data can be passed to the callback in
168       receive_data.
169
170       The paramlist will be supplied by the client. In addition, if the
171       receive_mode keywords buf and fillbuf are true, then on entry into the
172       receive_callback() routine, buf will contain the data sent by the
173       client. If buf is true but fillbuf is false, it becomes the callback's
174       responsibility to retrieve the data from the client, using the data fd
175       pointed to by the macro xpa_datafd(xpa).  If freebuf is true, then buf
176       will be freed when the callback is complete.
177
178       If, while the callback is performing its processing, an error occurs
179       that should be communicated to the client, then the routine XPAError
180       can be called:
181
182         XPAError(XPA xpa, char *s);
183
184       where s is an arbitrary error message.
185
186       The callback routine should return 0 if no error occurs, or -1 to
187       signal an error.
188

SEE ALSO

190       See xpa(n) for a list of XPA help pages
191
192
193
194version 2.1.15                   July 23, 2013                       xpanew(3)
Impressum