1xpanew(3) SAORD Documentation xpanew(3)
2
6 XPANew: create a new XPA access point
7
9 #include <xpa.h>
10 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
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 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 The help string is meant to be returned by a request from xpaget:
40 xpaget class:name -help
42 A send_callback and/or a receive_callback can be specified; at least
44 one of them must be specified.
45 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 The calling sequence for send_callback() is:
52 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 The send_mode string is of the form: "key1=value1,key2=value2,..." The
62 following keywords are recognized:
63 key value default explanation
65 ------ -------- -------- -----------
66 acl true/false true enable access control
67 freebuf true/false true free buf after callback completes
68 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 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 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 2. The send_callback can send data directly to the client by writing to
83 the fd pointed by the macro:
84 xpa_datafd(xpa)
86 Note that this fd is of the kind returned by socket() or open().
88 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 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 void XPASetFree(XPA xpa, void (*myfree)(void *), void *myfree_ptr);
104 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 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 XPAError(XPA xpa, char *s);
119 where s is an arbitrary error message. The returned error message
121 string will be of the form:
122 XPA$ERROR [error] (class:name ip:port)
124 If the callback wants to send a specific acknowledgment message back to
126 the client, the routine XPAMessage can be called:
127 XPAMessage(XPA xpa, char *s);
129 where s is an arbitrary error message. The returned error message
131 string will be of the form:
132 XPA$MESSAGE [message] (class:name ip:port)
134 Otherwise, a standard acknowledgment is sent back to the client after
136 the callback is completed.
137 The callback routine should return 0 if no error occurs, or -1 to
139 signal an error.
140 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 The calling sequence for receive_callback is:
147 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 The mode string is of the form: "key1=value1,key2=value2,..." The
157 following keywords are recognized:
158 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 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 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 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 XPAError(XPA xpa, char *s);
183 where s is an arbitrary error message.
185 The callback routine should return 0 if no error occurs, or -1 to
187 signal an error.
188
190 See xpa(n) for a list of XPA help pages
191version 2.1.15 July 23, 2013 xpanew(3)