1 /*----------------------------------------------------------------------------
2 Name: XmlBlasterAccess.h
3 Project: xmlBlaster.org
4 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
5 Comment: This combines the sync xmlBlaster access (XmlBlasterConnectionUnparsed.h)
6 with the pure callback implementation (CallbackServerUnparsed.h)
7 and adds threading to allow simultaneous access and callbacks.
8
9 Include this header in your client code.
10
11 The returned strings are not parsed, we need another layer
12 doing XML parsing with expat.
13 This library is thread safe, multiple client connections may
14 be established in parallel.
15 Author: "Marcel Ruff" <xmlBlaster@marcelruff.info>
16 Date: 05/2003
17 See: http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.html
18 -----------------------------------------------------------------------------*/
19 #ifndef _XmlBlasterAccess_H
20 #define _XmlBlasterAccess_H
21
22 #ifdef __cplusplus
23 #ifndef XMLBLASTER_C_COMPILE_AS_CPP /* 'g++ -DXMLBLASTER_C_COMPILE_AS_CPP ...' allows to compile the lib as C++ code */
24 extern "C" {
25 #endif
26 #endif
27
28 #include <util/msgUtil.h>
29 #include <util/Properties.h>
30 #include <util/Timeout.h>
31 #include <XmlBlasterAccessUnparsed.h>
32
33 #ifdef XB_USE_PTHREADS
34 # ifdef _WINDOWS
35 # include <pthreads/pthread.h> /* Our pthreads.h: For logging output of thread ID, for Windows and WinCE downloaded from http://sources.redhat.com/pthreads-win32 */
36 # else
37 # include <pthread.h> /* The original pthreads.h from the OS */
38 # endif
39 #endif
40
41
42 /*
43 NOTE: The struct name and the later typedef name are identical, we need this
44 to allow in C++ SocketDriver.h a forward declaration of the XmlBlasterAccess*
45 pointer (to avoid inclusion of this complete header)
46 */
47 struct XmlBlasterAccess;
48 struct ReturnQosStruct;
49
50 typedef XMLBLASTER_C_bool ( * XmlBlasterIsStateOk)(struct ReturnQosStruct *returnQos);
51 typedef struct ReturnQosStruct {
52 XmlBlasterIsStateOk isOk; /* State Info */
53 char *returnQos;
54 } ReturnQos;
55 typedef struct ReturnQosStruct ConnectReturnQos;
56 typedef struct ReturnQosStruct PublishReturnQos;
57 typedef struct ReturnQosStruct SubscribeReturnQos;
58 typedef struct ReturnQosStruct UnSubscribeReturnQos;
59 typedef struct ReturnQosStruct EraseReturnQos;
60 typedef struct ReturnQosStruct PingReturnQos;
61 /*
62 typedef struct PublishReturnQosStructArr {
63 uint32_t len;
64 PublishReturnQos *returnQosArr;
65 } PublishReturnQosArr;
66 typedef struct EraseReturnQosStructArr {
67 uint32_t len;
68 EraseReturnQos *returnQosArr;
69 } EraseReturnQosArr;
70 typedef struct UnSubscribeReturnQosStructArr {
71 uint32_t len;
72 UnSubscribeReturnQos *returnQosArr;
73 } UnSubscribeReturnQosArr;
74 */
75 typedef struct ReturnQosStructArr {
76 uint32_t len;
77 ReturnQos *returnQosArr;
78 } ReturnQosArr;
79 typedef struct ReturnQosStructArr PublishReturnQosArr;
80 typedef struct ReturnQosStructArr UnSubscribeReturnQosArr;
81 typedef struct ReturnQosStructArr EraseReturnQosArr;
82
83 typedef struct KeyStruct {
84 char *key;
85 } Key;
86 typedef struct KeyStruct PublishKey;
87 typedef struct KeyStruct GetKey;
88 typedef struct KeyStruct SubscribeKey;
89 typedef struct KeyStruct UnSubscribeKey;
90 typedef struct KeyStruct EraseKey;
91 typedef struct QosStruct {
92 char *qos;
93 } Qos;
94 typedef struct QosStruct ConnectQos;
95 typedef struct QosStruct DisconnectQos;
96 typedef struct QosStruct PublishQos;
97 typedef struct QosStruct GetQos;
98 typedef struct QosStruct SubscribeQos;
99 typedef struct QosStruct UnSubscribeQos;
100 typedef struct QosStruct EraseQos;
101 typedef struct QosStruct PingQos;
102
103
104 typedef XMLBLASTER_C_bool (*XmlBlasterAccessUpdateFp)(struct XmlBlasterAccess* xb, MsgUnitArr *msg, XmlBlasterException *xmlBlasterException);
105 /* Design decision: The qos and key remain char* and not ConnectQosStruct* to simplify usage */
106 /* Declare function pointers to use in struct to simulate object oriented access */
107 typedef ConnectReturnQos *( * XmlBlasterAccessConnect)(struct XmlBlasterAccess *xb, const ConnectQos * connectQos, XmlBlasterAccessUpdateFp update, XmlBlasterException *exception);
108 typedef XMLBLASTER_C_bool ( * XmlBlasterAccessDisconnect)(struct XmlBlasterAccess *xb, const DisconnectQos * disconnectQos, XmlBlasterException *exception);
109 typedef PublishReturnQos *( * XmlBlasterAccessPublish)(struct XmlBlasterAccess *xb, MsgUnit *msgUnit, XmlBlasterException *exception);
110 typedef PublishReturnQosArr *( * XmlBlasterAccessPublishArr)(struct XmlBlasterAccess *xb, MsgUnitArr *msgUnitArr, XmlBlasterException *exception);
111 typedef void ( * XmlBlasterAccessPublishOneway)(struct XmlBlasterAccess *xb, MsgUnitArr *msgUnitArr, XmlBlasterException *exception);
112 typedef SubscribeReturnQos *( * XmlBlasterAccessSubscribe)(struct XmlBlasterAccess *xb, const SubscribeKey * subscribeKey, const SubscribeQos * subscribeQos, XmlBlasterException *exception);
113 typedef UnSubscribeReturnQosArr *( * XmlBlasterAccessUnSubscribe)(struct XmlBlasterAccess *xb, const UnSubscribeKey * unSubscribeKey, const UnSubscribeQos * unSubscribeQos, XmlBlasterException *exception);
114 typedef UnSubscribeReturnQosArr *( * XmlBlasterAccessErase)(struct XmlBlasterAccess *xb, const EraseKey * eraseKey, const EraseQos * eraseQos, XmlBlasterException *exception);
115 typedef MsgUnitArr *( * XmlBlasterAccessGet)(struct XmlBlasterAccess *xb, const GetKey * getKey, const GetQos * getQos, XmlBlasterException *exception);
116 typedef PingReturnQos *( * XmlBlasterAccessPing)(struct XmlBlasterAccess *xb, const PingQos * pingQos, XmlBlasterException *exception);
117 typedef XMLBLASTER_C_bool ( * XmlBlasterAccessIsConnected)(struct XmlBlasterAccess *xb);
118
119 typedef enum XBCONSTATE_ENUM {
120 XBCONSTATE_UNDEF = -1,
121 XBCONSTATE_SOCKALIVE = 0, /**< socket is connected */
122 XBCONSTATE_POLLING = 1, /**< trying to reconnect */
123 XBCONSTATE_DEAD = 2, /**< we have given up */
124 XBCONSTATE_LOGGEDINALIVE = 3 /**< socket is connected and connectQos was successful (~postAlive) */
125 } XBCONSTATE;
126 /**
127 * @param xa This pointer
128 * @param oldState e.g. XBCONSTATE_ALIVE
129 * @param newState e.g. XBCONSTATE_POLLING
130 * @param exception Is NULL if no exception is related
131 * @param userData Bounced back pointer from registerConnectionListener()
132 */
133 typedef void ( * ConnectionListenerCbFp)(struct XmlBlasterAccess *xa, XBCONSTATE oldState, XBCONSTATE newState, XmlBlasterException *exception, void *userData);
134 /**
135 * Register a listener to get events about connection status changes.
136 * @param xa The this pointer
137 * @param cbFp NULL or your listener implementation on connection state changes (XBCONSTATE_ALIVE | XBCONSTATE_POLLING | XBCONSTATE_DEAD)
138 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/client.failsafe.html">client.failsafe requirement</a>
139 */
140 typedef void (* XmlBlasterAccessRegisterConnectionListener)(struct XmlBlasterAccess *xa, ConnectionListenerCbFp cbFp, void *userData);
141 /**
142 * Ge human readable connection state.
143 * @param state XBCONSTATE_ALIVE etc
144 * @return "ALIVE" etc
145 */
146 Dll_Export extern const char *connectionStateToStr(XBCONSTATE state);
147
148 /**
149 * All client access to xmlBlaster goes over this struct and its function pointers.
150 *
151 * All function pointers expect a 'this' pointer of type #XmlBlasterAccess
152 * and return XmlBlasterException#errorCode="communication.noConnection" if connection
153 * to xmlBlaster is lost.
154 *
155 * Create an instance of #XmlBlasterAccess with a call to #getXmlBlasterAccess()
156 * and you are ready to access xmlBlaster. Don't forget to free everything when you don't need
157 * xmlBlaster access anymore with a call to #freeXmlBlasterAccess()
158 *
159 * See HelloWorld3.c for a complete usage example.
160 *
161 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/client.c.socket.html
162 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/protocol.socket.html
163 */
164 typedef struct Dll_Export XmlBlasterAccess {
165 /* public: */
166 int argc; /**< The number of #argv entries */
167 const char * const *argv; /**< Environment configuration, usually from the command line */
168 Properties *props; /**< Further configuration parameters */
169 void *userObject; /**< A client can use this pointer to point to any client specific information */
170 ConnectQos *connectQos;
171 ConnectReturnQos *connectReturnQos;
172
173 XmlBlasterAccessRegisterConnectionListener registerConnectionListener;
174
175 XmlBlasterAccessGenericFp userFp; /**< A client can use this function pointer to do any client specific handling */
176 /**
177 * Connect to the server.
178 * @param xa The 'this' pointer
179 * @param qos The QoS struct which contains the xml markup string to connect, typically
180 * <pre>
181 * <qos>
182 * <securityService type='htpasswd' version='1.0'>
183 * <user>fritz</user>
184 * <passwd>secret</passwd>
185 * </securityService>
186 * <queue relating='callback' maxEntries='100' maxEntriesCache='100'>
187 * <callback type='SOCKET' sessionId='%s'>
188 * socket://myServer.myCompany.com:6645
189 * </callback>
190 * </queue>
191 * </qos>
192 * </pre>
193 * You can safely destroy the stuct after this call
194 * @param clientUpdateFp The clients callback function pointer #UpdateFp, if NULL our default handler is used
195 * Is ignored if set by initialize already.
196 * @param The exception struct, exception->errorCode is filled on exception
197 * @return The ConnectReturnQos raw xml string, you need to free() it
198 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.connect.html
199 */
200 XmlBlasterAccessConnect connect;
201 /**
202 * Disconnect from server.
203 * @param xa The 'this' pointer
204 * @param qos The QoS xml markup string to disconnect
205 * @param The exception struct, exception->errorCode is filled on exception
206 * @return false on exception
207 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.publish.html
208 */
209 XmlBlasterAccessDisconnect disconnect;
210 /**
211 * Publish a message.
212 *
213 * @param xa The 'this' pointer to simulate C++ classes
214 * @param msgUnit The message of type #MsgUnit you want to send.
215 * @param xmlBlasterException If *xmlBlasterException.errorCode!=0 this #XmlBlasterException
216 * is filled with the exception details and you should ignore the returned QosArr.
217 * @return The QoS string with the response from xmlBlaster. You have to free it with a call to #xmlBlasterFree.
218 * If *xmlBlasterException.errorCode!=0 you need to ignore the returned data and don't need to free it.
219 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.publish.html
220 */
221 XmlBlasterAccessPublish publish;
222 /**
223 * Publish an array of messages.
224 *
225 * @param xa The 'this' pointer to simulate C++ classes
226 * @param msgUnitArr The messages of type #MsgUnitArr you want to send.
227 * @param xmlBlasterException If *xmlBlasterException.errorCode!=0 this #XmlBlasterException is filled with the exception details and
228 * you should ignore the returned QosArr.
229 * @return The #QosArr struct with the response from xmlBlaster. You have to free it with a call to #freeQosArr.
230 * If *xmlBlasterException.errorCode!=0 you need to ignore the returned data and don't need to free it.
231 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.publish.html
232 */
233 XmlBlasterAccessPublishArr publishArr;
234 /**
235 * Publish oneway an array of messages.
236 *
237 * Oneway messages don't return something, the server does not acknowledge (ACK) them.
238 *
239 * @param xa The 'this' pointer to simulate C++ classes
240 * @param msgUnitArr The messages of type #MsgUnitArr you want to send.
241 * @param xmlBlasterException If *xmlBlasterException.errorCode!=0 this #XmlBlasterException is filled with the exception details and
242 * you should ignore the returned QosArr.
243 * @return The #QosArr struct with the response from xmlBlaster. You have to free it with a call to #freeQosArr.
244 * If *xmlBlasterException.errorCode!=0 you need to ignore the returned data and don't need to free it.
245 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.publish.html
246 */
247 XmlBlasterAccessPublishOneway publishOneway;
248 /**
249 * Subscribe to messages.
250 *
251 * @param xa The 'this' pointer to simulate C++ classes
252 * @param key The key xml string
253 * @param qos The QoS xml string
254 * @param xmlBlasterException If *xmlBlasterException.errorCode!=0 this #XmlBlasterException is filled with the exception details and
255 * you should ignore the returned QosArr.
256 * @return The QoS string with the response from xmlBlaster. You have to free it with a call to #xmlBlasterFree.
257 * If *xmlBlasterException.errorCode!=0 you need to ignore the returned data and don't need to free it.
258 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.subscribe.html
259 */
260 XmlBlasterAccessSubscribe subscribe;
261 XmlBlasterAccessUnSubscribe unSubscribe;
262 XmlBlasterAccessErase erase;
263 XmlBlasterAccessGet get;
264 XmlBlasterAccessPing ping;
265 /**
266 * Has the connect() method successfully passed?
267 * <p>
268 * Note that this contains no information about the current connection state
269 * of the protocol layer.
270 * </p>
271 * @param xa The 'this' pointer
272 * @return true If the connection() method was invoked without exception
273 */
274 XmlBlasterAccessIsConnected isConnected;
275 XMLBLASTER_LOG_LEVEL logLevel;
276 XmlBlasterLogging log;
277 void *logUserP; /**< For outside users to pass a user object back to the logging implementation */
278 /* private: */
279 XmlBlasterAccessUnparsed *connectionP;
280 Timeout *pingPollTimer;
281 ConnectionListenerCbFp connectionListenerCbFp;
282 void *connectionListenerUserData;
283
284 XmlBlasterAccessUpdateFp clientsUpdateFp; /**< Remember clients callback function during polling */
285
286 long pingInterval;
287 long retries;
288 long delay;
289 XBCONSTATE connnectionState; /*XBCONSTATE_SOCKALIVE etc.*/
290
291 bool isShutdown;
292 } XmlBlasterAccess;
293
294 /**
295 * Create an instance to access xmlBlaster.
296 * This is usually the first call of a client.
297 *
298 * Every call creates a new and independent client access instance to xmlBlaster
299 *
300 * Our properties point on the passed argv memory, so you should
301 * not free the original argv memory before you free #XmlBlasterAccess.
302 *
303 * @param argc The number of argv properties
304 * @param argv The command line properties, see #createProperties() for a specification, can be NULL for argc==0
305 * @return NULL if bootstrapping failed. If not NULL you need to free memory when you are done
306 * usually by calling #freeXmlBlasterAccess().
307 */
308 Dll_Export extern XmlBlasterAccess *getXmlBlasterAccess(int argc, const char* const* argv);
309
310 /**
311 * Free your instance after accessing xmlBlaster.
312 */
313 Dll_Export extern void freeXmlBlasterAccess(XmlBlasterAccess *xmlBlasterAccess);
314
315 Dll_Export extern Key *createXmlBlasterKey(const char * keyXml);
316 Dll_Export extern Qos *createXmlBlasterQos(const char * qosXml);
317 Dll_Export extern ReturnQos *createXmlBlasterReturnQos(const char * qosXml);
318 Dll_Export extern ReturnQosArr *createXmlBlasterReturnQosArr(QosArr * qosArr);
319 /*Dll_Export extern QosArr *createXmlBlasterQosArr(const char * qosArr);*/
320 Dll_Export extern void freeXmlBlasterKey(Key * key);
321 Dll_Export extern void freeXmlBlasterQos(Qos * qos);
322 Dll_Export extern void freeXmlBlasterReturnQos(ReturnQos * returnQos);
323 Dll_Export extern void freeXmlBlasterReturnQosArr(ReturnQosArr * returnQosArr);
324
325 /**
326 * Help usage
327 * @param usage Please pass a string with at least XMLBLASTER_MAX_USAGE_LEN chars allocated (or on stack)
328 * @return Your usage pointer filled with informations
329 */
330 Dll_Export extern const char *XmlBlasterAccessUsage(char *usage);
331
332 #ifdef __cplusplus
333 #ifndef XMLBLASTER_C_COMPILE_AS_CPP
334 }
335 #endif
336 #endif
337
338 #endif /* _XmlBlasterAccess_H */
syntax highlighted by Code2HTML, v. 0.9.1