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 environ‐
27 ment variable XPA_NSINET, which takes the form :. If no such environ‐
28 ment variable exists, then xpans is started on the current machine lis‐
29 tening on port 14285. It also uses 14286 as a known port for its pub‐
30 lic access point (so that routines do not have to go to the name server
31 to find the name server ip and port!) As of XPA 2.1.1, version infor‐
32 mation is exchanged between the xpans process and the new access point.
33 If the access point uses an XPA major/minor version newer than xpans, a
34 warning is issued by both processes, since mixing of new servers and
35 old xpa programs (xpaset, xpaget, xpans, etc.) is not likely to work.
36 You can turn off the warning message by setting the XPA_VERSIONCHECK
37 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 request‐
49 ing client.
50 The calling sequence for send_callback() is:
52 int send_callback(void *send_data, void *call_data,
54 char *paramlist, char **buf, int *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 addi‐
70 tion, client-specific data can be passed to the callback in send_data.
71 The paramlist will be supplied by the client as qualifying parameters
73 for the callback. There are two ways in which the send_callback() rou‐
74 tine can send data back to the client:
75 1. The send_callback() routine can fill in a buffer and pass back a
77 pointer to this buffer. An integer len also is returned to specify the
78 number of bytes of data in buf. XPA will send this buffer to the
79 client after the callback is complete.
80 2. The send_callback can send data directly to the client by writing to
82 the fd pointed by the macro:
83 xpa_datafd(xpa)
85 Note that this fd is of the kind returned by socket() or open().
87 If a buf has been allocated by a standard malloc routine, filled, and
89 returned to XPA, then freebuf generally is set so that the buffer will
90 be freed automatically when the callback is completed and data has been
91 sent to the client. If a static buf is returned, freebuf should be set
92 to false to avoid a system error when freeing static storage. Note
93 that default value for freebuf implies that the callback will allocate
94 a buffer rather than use static storage.
95 On the other hand, if buf is dynamically allocated using a method other
97 than a standard malloc/calloc/realloc routine (e.g. using Perl's memory
98 allocation and garbage collection scheme), then it is necessary to tell
99 XPA how to free the allocated buffer. To do this, use the XPASetFree()
100 routine within your callback:
101 void XPASetFree(XPA xpa, void (*myfree)(void *), void *myfree_ptr);
103 The first argument is the usual XPA handle. The second argument is the
105 special routine to call to free your allocated memory. The third argu‐
106 ment is an optional pointer. If not NULL, the specified free routine
107 is called with that pointer as its sole argument. If NULL, the free
108 routine is called with the standard buf pointer as its sole argument.
109 This is useful in cases where there is a mapping between the buffer
110 pointer and the actual allocated memory location, and the special rou‐
111 tine is expecting to be passed the former.
112 If, while the callback performs its processing, an error occurs that
114 should be communicated to the client, then the routine XPAError should
115 be called:
116 XPAError(XPA xpa, char *s);
118 where s is an arbitrary error message. The returned error message
120 string will be of the form:
121 XPA$ERROR [error] (class:name ip:port)
123 If the callback wants to send a specific acknowledgment message back to
125 the client, the routine XPAMessage can be called:
126 XPAMessage(XPA xpa, char *s);
128 where s is an arbitrary error message. The returned error message
130 string will be of the form:
131 XPA$MESSAGE [message] (class:name ip:port)
133 Otherwise, a standard acknowledgment is sent back to the client after
135 the callback is completed.
136 The callback routine should return 0 if no error occurs, or -1 to sig‐
138 nal an error.
139 A receive_callback can be specified that will be executed in response
141 to an external request from the xpaset program, or the XPASet (or
142 XPASetFd()) routine. This callback is used to process data received
143 from an external process.
144 The calling sequence for receive_callback is:
146 int receive_callback(void *receive_data, void *call_data,
148 char *paramlist, char *buf, int len)
149 {
150 XPA xpa = (XPA)call_data;
151 ...
152 return(stat);
153 }
154 The mode string is of the form: "key1=value1,key2=value2,..." The fol‐
156 lowing keywords are recognized:
157 key value default explanation
159 ------ -------- -------- -----------
160 acl true/false true enable access control
161 buf true/false true server expects data bytes from client
162 fillbuf true/false true read data into buf before executing callback
163 freebuf true/false true free buf after callback completes
164 The call_data should be recast to the XPA struct as shown. In addi‐
166 tion, client-specific data can be passed to the callback in
167 receive_data.
168 The paramlist will be supplied by the client. In addition, if the
170 receive_mode keywords buf and fillbuf are true, then on entry into the
171 receive_callback() routine, buf will contain the data sent by the
172 client. If buf is true but fillbuf is false, it becomes the callback's
173 responsibility to retrieve the data from the client, using the data fd
174 pointed to by the macro xpa_datafd(xpa). If freebuf is true, then buf
175 will be freed when the callback is complete.
176 If, while the callback is performing its processing, an error occurs
178 that should be communicated to the client, then the routine XPAError
179 can be called:
180 XPAError(XPA xpa, char *s);
182 where s is an arbitrary error message.
184 The callback routine should return 0 if no error occurs, or -1 to sig‐
186 nal an error.
187
189 See xpa(n) for a list of XPA help pages
190version 2.1.12 January 26, 2010 xpanew(3)