1 /*----------------------------------------------------------------------------
2 Name: XmlBlasterAccessUnparsed.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 _XmlBlasterAccessUnparsed_H
20 #define _XmlBlasterAccessUnparsed_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 <XmlBlasterConnectionUnparsed.h>
31 #include <CallbackServerUnparsed.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 /* The following comment is used by doxygen for the main html page: */
42 /*! \mainpage Hints about the C client library usage.
43 *
44 * \section intro_sec The C client library
45 *
46 * The xmlBlaster C client library supports access to xmlBlaster with asynchronous callbacks.
47 * Details about compilation and its usage can be found in the
48 * http://www.xmlblaster.org/xmlBlaster/doc/requirements/client.c.socket.html requirement.
49 *
50 * As a C developer your entry point to use is the struct XmlBlasterAccessUnparsed and
51 * a complete overview demo code is HelloWorld3.c
52 *
53 * \section queue_sec The C persistent queue
54 *
55 * There is a C based persistent queue available. Currently this C client library and
56 * the queue implementation are used in the C++ client library for easy xmlBlaster connection
57 * and client side queuing.
58 * As a C developer your entry point to use is the struct I_QueueStruct and a source code example
59 * is TestQueue.c
60 *
61 * For details read the
62 * http://www.xmlblaster.org/xmlBlaster/doc/requirements/client.c.queue.html requirement.
63 *
64 * \section cpp_sec The C++ client library
65 * The C++ client library offers many extended client side features compared to the C library.
66 * If you need those additional features and the library size is not the primary concern
67 * you should consider to use the C++ library.
68 *
69 * For details read the
70 * http://www.xmlblaster.org/xmlBlaster/doc/requirements/client.cpp.html requirement
71 * and look at the API documentation at http://www.xmlblaster.org/xmlBlaster/doc/doxygen/cpp/html/index.html
72 */
73
74
75 /*
76 NOTE: The struct name and the later typedef name are identical, we need this
77 to allow in C++ SocketDriver.h a forward declaration of the XmlBlasterAccessUnparsed*
78 pointer (to avoid inclusion of this complete header)
79 */
80 struct XmlBlasterAccessUnparsed;
81
82 typedef XMLBLASTER_C_bool (*UpdateFp)(MsgUnitArr *msg, void *userData, XmlBlasterException *xmlBlasterException);
83
84 /* Declare function pointers to use in struct to simulate object oriented access */
85 typedef char *( * XmlBlasterAccessUnparsedConnect)(struct XmlBlasterAccessUnparsed *xb, const char * const qos, UpdateFp update, XmlBlasterException *exception);
86 typedef bool ( * XmlBlasterAccessUnparsedInitialize)(struct XmlBlasterAccessUnparsed *xa, UpdateFp update, XmlBlasterException *exception);
87 typedef bool ( * XmlBlasterAccessUnparsedDisconnect)(struct XmlBlasterAccessUnparsed *xb, const char * qos, XmlBlasterException *exception);
88 typedef char *( * XmlBlasterAccessUnparsedPublish)(struct XmlBlasterAccessUnparsed *xb, MsgUnit *msgUnit, XmlBlasterException *exception);
89 typedef QosArr *( * XmlBlasterAccessUnparsedPublishArr)(struct XmlBlasterAccessUnparsed *xb, MsgUnitArr *msgUnitArr, XmlBlasterException *exception);
90 typedef void ( * XmlBlasterAccessUnparsedPublishOneway)(struct XmlBlasterAccessUnparsed *xb, MsgUnitArr *msgUnitArr, XmlBlasterException *exception);
91 typedef char *( * XmlBlasterAccessUnparsedSubscribe)(struct XmlBlasterAccessUnparsed *xb, const char * const key, const char * qos, XmlBlasterException *exception);
92 typedef QosArr *( * XmlBlasterAccessUnparsedUnSubscribe)(struct XmlBlasterAccessUnparsed *xb, const char * const key, const char * qos, XmlBlasterException *exception);
93 typedef QosArr *( * XmlBlasterAccessUnparsedErase)(struct XmlBlasterAccessUnparsed *xb, const char * const key, const char * qos, XmlBlasterException *exception);
94 typedef MsgUnitArr *( * XmlBlasterAccessUnparsedGet)(struct XmlBlasterAccessUnparsed *xb, const char * const key, const char * qos, XmlBlasterException *exception);
95 typedef char *( * XmlBlasterAccessUnparsedPing)(struct XmlBlasterAccessUnparsed *xb, const char * const qos, XmlBlasterException *exception);
96 typedef bool ( * XmlBlasterAccessUnparsedIsConnected)(struct XmlBlasterAccessUnparsed *xb);
97
98 typedef void ( * XmlBlasterAccessGenericFp)();
99
100 /**
101 * All client access to xmlBlaster goes over this struct and its function pointers.
102 *
103 * All function pointers expect a 'this' pointer of type #XmlBlasterAccessUnparsed
104 * and return XmlBlasterException#errorCode="communication.noConnection" if connection
105 * to xmlBlaster is lost.
106 *
107 * Create an instance of #XmlBlasterAccessUnparsed with a call to #getXmlBlasterAccessUnparsed()
108 * and you are ready to access xmlBlaster. Don't forget to free everything when you don't need
109 * xmlBlaster access anymore with a call to #freeXmlBlasterAccessUnparsed()
110 *
111 * See HelloWorld3.c for a complete usage example.
112 *
113 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/client.c.socket.html
114 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/protocol.socket.html
115 */
116 typedef struct Dll_Export XmlBlasterAccessUnparsed {
117 /* public: */
118 int argc; /**< The number of #argv entries */
119 const char * const *argv; /**< Environment configuration, usually from the command line */
120 Properties *props; /**< Further configuration parameters */
121 void *userObject; /**< A client can use this pointer to point to any client specific information */
122 XmlBlasterAccessGenericFp userFp; /**< A client can use this function pointer to do any client specific handling */
123 /**
124 * Connect to the server.
125 * @param xa The 'this' pointer
126 * @param qos The QoS xml markup string to connect, typically
127 * <pre>
128 * <qos>
129 * <securityService type='htpasswd' version='1.0'>
130 * <user>fritz</user>
131 * <passwd>secret</passwd>
132 * </securityService>
133 * <queue relating='callback' maxEntries='100' maxEntriesCache='100'>
134 * <callback type='SOCKET' sessionId='%s'>
135 * socket://myServer.myCompany.com:6645
136 * </callback>
137 * </queue>
138 * </qos>
139 * </pre>
140 * @param clientUpdateFp The clients callback function pointer #UpdateFp, if NULL our default handler is used
141 * Is ignored if set by initialize already.
142 * @param The exception struct, exception->errorCode is filled on exception
143 * @return The ConnectReturnQos raw xml string, you need to free() it
144 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.connect.html
145 */
146 XmlBlasterAccessUnparsedConnect connect;
147 /**
148 * Creates client side connection object and the callback server and does the low level IP connection.
149 * This method is automatically called by #connect() so you usually only
150 * call it explicitly if you are interested in the callback server settings.
151 * @param xa The 'this' pointer
152 * @param clientUpdateFp The clients callback handler function #UpdateFp. If NULL our default handler is used
153 * @return true on success
154 */
155 XmlBlasterAccessUnparsedInitialize initialize;
156 /**
157 * Disconnect from server.
158 * @param xa The 'this' pointer
159 * @param qos The QoS xml markup string to disconnect
160 * @param The exception struct, exception->errorCode is filled on exception
161 * @return false on exception
162 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.publish.html
163 */
164 XmlBlasterAccessUnparsedDisconnect disconnect;
165 /**
166 * Publish a message.
167 *
168 * @param xa The 'this' pointer to simulate C++ classes
169 * @param msgUnit The message of type #MsgUnit you want to send.
170 * @param xmlBlasterException If *xmlBlasterException.errorCode!=0 this #XmlBlasterException
171 * is filled with the exception details and you should ignore the returned QosArr.
172 * @return The QoS string with the response from xmlBlaster. You have to free it with a call to #xmlBlasterFree.
173 * If *xmlBlasterException.errorCode!=0 you need to ignore the returned data and don't need to free it.
174 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.publish.html
175 */
176 XmlBlasterAccessUnparsedPublish publish;
177 /**
178 * Publish an array of messages.
179 *
180 * @param xa The 'this' pointer to simulate C++ classes
181 * @param msgUnitArr The messages of type #MsgUnitArr you want to send.
182 * @param xmlBlasterException If *xmlBlasterException.errorCode!=0 this #XmlBlasterException is filled with the exception details and
183 * you should ignore the returned QosArr.
184 * @return The #QosArr struct with the response from xmlBlaster. You have to free it with a call to #freeQosArr.
185 * If *xmlBlasterException.errorCode!=0 you need to ignore the returned data and don't need to free it.
186 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.publish.html
187 */
188 XmlBlasterAccessUnparsedPublishArr publishArr;
189 /**
190 * Publish oneway an array of messages.
191 *
192 * Oneway messages don't return something, the server does not acknowledge (ACK) them.
193 *
194 * @param xa The 'this' pointer to simulate C++ classes
195 * @param msgUnitArr The messages of type #MsgUnitArr you want to send.
196 * @param xmlBlasterException If *xmlBlasterException.errorCode!=0 this #XmlBlasterException is filled with the exception details and
197 * you should ignore the returned QosArr.
198 * @return The #QosArr struct with the response from xmlBlaster. You have to free it with a call to #freeQosArr.
199 * If *xmlBlasterException.errorCode!=0 you need to ignore the returned data and don't need to free it.
200 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.publish.html
201 */
202 XmlBlasterAccessUnparsedPublishOneway publishOneway;
203 /**
204 * Subscribe to messages.
205 *
206 * @param xa The 'this' pointer to simulate C++ classes
207 * @param key The key xml string
208 * @param qos The QoS xml string
209 * @param xmlBlasterException If *xmlBlasterException.errorCode!=0 this #XmlBlasterException is filled with the exception details and
210 * you should ignore the returned QosArr.
211 * @return The QoS string with the response from xmlBlaster. You have to free it with a call to #xmlBlasterFree.
212 * If *xmlBlasterException.errorCode!=0 you need to ignore the returned data and don't need to free it.
213 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.subscribe.html
214 */
215 XmlBlasterAccessUnparsedSubscribe subscribe;
216 XmlBlasterAccessUnparsedUnSubscribe unSubscribe;
217 XmlBlasterAccessUnparsedErase erase;
218 XmlBlasterAccessUnparsedGet get;
219 XmlBlasterAccessUnparsedPing ping;
220 /**
221 * Check if we are connected to xmlBlaster.
222 * @param xa The 'this' pointer
223 * @return #bool true or false
224 */
225 XmlBlasterAccessUnparsedIsConnected isConnected;
226 XMLBLASTER_LOG_LEVEL logLevel;
227 XmlBlasterLogging log;
228 void *logUserP; /**< For outside users to pass a user object back to the logging implementation */
229 /* private: */
230 XmlBlasterConnectionUnparsed *connectionP;
231 CallbackServerUnparsed *callbackP;
232 bool isInitialized;
233 bool isShutdown;
234 /**
235 * Here we asynchronously receive the callback from xmlBlaster.
236 *
237 * NOTE: After this call the memory of #MsgUnitArr is freed immediately by #CallbackServerUnparsed.
238 * So you need to take a copy of all message members if needed out of the scope of this function.
239 *
240 * @param msgUnitArr The messages of type #MsgUnitArr from the server, use MsgUnit#responseQos to transport the return value.
241 * If responseQos is not NULL it will be free()'d as well by us.
242 * @param userData An optional pointer from the client with client specific data which is delivered back.
243 * Here userData is always the '#XmlBlasterAccessUnparsed *' pointer
244 * @param xmlBlasterException This points on a valid struct of type #XmlBlasterException,
245 * so you only need to fill errorCode with #strcpy
246 * and the returned pointer is ignored and the exception is thrown to xmlBlaster.
247 * @return Return #bool true if everything is OK
248 * Return false if you want to throw an exception, please fill #XmlBlasterException in such a case.
249 * If false and *xmlBlasterException.errorCode==0 we don't send a return message
250 * (useful for update dispatcher thread to do it later)
251 * @see http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.update.html
252 * @todo Return void instead of #bool
253 */
254 UpdateFp clientsUpdateFp;
255
256 bool callbackMultiThreaded; /**< Shall update messages be transported to the client code in a thread per request? */
257 bool lowLevelAutoAck;
258 long responseTimeout;
259 pthread_t callbackThreadId;
260 char threadCounter;
261 pthread_mutex_t writenMutex; /**< Protect writing n bytes to the socket */
262 pthread_mutex_t readnMutex; /**< Protect reading n bytes from the socket */
263 } XmlBlasterAccessUnparsed;
264
265 /**
266 * Create an instance to access xmlBlaster.
267 * This is usually the first call of a client.
268 *
269 * Every call creates a new and independent client access instance to xmlBlaster
270 *
271 * Our properties point on the passed argv memory, so you should
272 * not free the original argv memory before you free #XmlBlasterAccessUnparsed.
273 *
274 * @param argc The number of argv properties
275 * @param argv The command line properties, see #createProperties() for a specification, can be NULL for argc==0
276 * @return NULL if bootstrapping failed. If not NULL you need to free memory when you are done
277 * usually by calling #freeXmlBlasterAccessUnparsed().
278 */
279 Dll_Export extern XmlBlasterAccessUnparsed *getXmlBlasterAccessUnparsed(int argc, const char* const* argv);
280
281 /**
282 * Free your instance after accessing xmlBlaster.
283 */
284 Dll_Export extern void freeXmlBlasterAccessUnparsed(XmlBlasterAccessUnparsed *xmlBlasterAccess);
285
286 /**
287 * Help usage
288 * @param usage Please pass a string with at least XMLBLASTER_MAX_USAGE_LEN chars allocated (or on stack)
289 * @return Your usage pointer filled with informations
290 */
291 Dll_Export extern const char *xmlBlasterAccessUnparsedUsage(char *usage);
292
293 #ifdef __cplusplus
294 #ifndef XMLBLASTER_C_COMPILE_AS_CPP
295 }
296 #endif
297 #endif
298
299 #endif /* _XmlBlasterAccessUnparsed_H */
syntax highlighted by Code2HTML, v. 0.9.1