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 receive_callback()
74 routine can send data back to the client:
75 1. The receive_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 receive_callback can send data directly to the client by writing
82 to 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, filled, and returned to XPA, then freebuf
89 generally is set so that it will be freed automatically when the call‐
90 back is completed and data has been sent to the client. If a static
91 buf is returned, freebuf should be false to avoid a system error when
92 freeing static storage. Note that default value for freebuf implies
93 that the callback will allocate a buffer rather than use static stor‐
94 age.
95 If, while the callback performs its processing, an error occurs that
97 should be communicated to the client, then the routine XPAError should
98 be called:
99 XPAError(XPA xpa, char *s);
101 where s is an arbitrary error message. The returned error message
103 string will be of the form:
104 XPA$ERROR [error] (class:name ip:port)
106 If the callback wants to send a specific acknowledgment message back to
108 the client, the routine XPAMessage can be called:
109 XPAMessage(XPA xpa, char *s);
111 where s is an arbitrary error message. The returned error message
113 string will be of the form:
114 XPA$MESSAGE [message] (class:name ip:port)
116 Otherwise, a standard acknowledgment is sent back to the client after
118 the callback is completed.
119 The callback routine should return 0 if no error occurs, or -1 to sig‐
121 nal an error.
122 A receive_callback can be specified that will be executed in response
124 to an external request from the xpaset program, or the XPASet (or
125 XPASetFd()) routine. This callback is used to process data received
126 from an external process.
127 The calling sequence for receive_callback is:
129 int receive_callback(void *receive_data, void *call_data,
131 char *paramlist, char *buf, int len)
132 {
133 XPA xpa = (XPA)call_data;
134 ...
135 return(stat);
136 }
137 The mode string is of the form: "key1=value1,key2=value2,..." The fol‐
139 lowing keywords are recognized:
140 key value default explanation
142 ------ -------- -------- -----------
143 acl true/false true enable access control
144 buf true/false true server expects data bytes from client
145 fillbuf true/false true read data into buf before executing callback
146 freebuf true/false true free buf after callback completes
147 The call_data should be recast to the XPA struct as shown. In addi‐
149 tion, client-specific data can be passed to the callback in
150 receive_data.
151 The paramlist will be supplied by the client. In addition, if the
153 receive_mode keywords buf and fillbuf are true, then on entry into the
154 receive_callback() routine, buf will contain the data sent by the
155 client. If buf is true but fillbuf is false, it becomes the callback's
156 responsibility to retrieve the data from the client, using the data fd
157 pointed to by the macro xpa_datafd(xpa). If freebuf is true, then buf
158 will be freed when the callback is complete.
159 If, while the callback is performing its processing, an error occurs
161 that should be communicated to the client, then the routine XPAError
162 can be called:
163 XPAError(XPA xpa, char *s);
165 where s is an arbitrary error message.
167 The callback routine should return 0 if no error occurs, or -1 to sig‐
169 nal an error.
170
172 See xpa(n) for a list of XPA help pages
173version 2.1.8 November 1, 2007 xpanew(3)