change log updated
[public/netxms.git] / include / strophe.h
1 /* strophe.h
2 ** strophe XMPP client library C API
3 **
4 ** Copyright (C) 2005-2009 Collecta, Inc.
5 **
6 ** This software is provided AS-IS with no warranty, either express or
7 ** implied.
8 **
9 ** This software is dual licensed under the MIT and GPLv3 licenses.
10 */
11
12 /** @file
13 * Strophe public C API definitions.
14 */
15
16 #ifndef __LIBSTROPHE_STROPHE_H__
17 #define __LIBSTROPHE_STROPHE_H__
18
19 #ifdef _WIN32
20 #ifdef LIBSTROPHE_EXPORTS
21 #define LIBSTROPHE_EXPORTABLE __declspec(dllexport)
22 #else
23 #define LIBSTROPHE_EXPORTABLE __declspec(dllimport)
24 #endif
25 #else
26 #define LIBSTROPHE_EXPORTABLE
27 #endif
28
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32
33 #include <stdio.h>
34
35 /* namespace defines */
36 /** @def XMPP_NS_CLIENT
37 * Namespace definition for 'jabber:client'.
38 */
39 #define XMPP_NS_CLIENT "jabber:client"
40 /** @def XMPP_NS_COMPONENT
41 * Namespace definition for 'jabber:component:accept'.
42 */
43 #define XMPP_NS_COMPONENT "jabber:component:accept"
44 /** @def XMPP_NS_STREAMS
45 * Namespace definition for 'http://etherx.jabber.org/streams'.
46 */
47 #define XMPP_NS_STREAMS "http://etherx.jabber.org/streams"
48 /** @def XMPP_NS_STREAMS_IETF
49 * Namespace definition for 'urn:ietf:params:xml:ns:xmpp-streams'.
50 */
51 #define XMPP_NS_STREAMS_IETF "urn:ietf:params:xml:ns:xmpp-streams"
52 /** @def XMPP_NS_TLS
53 * Namespace definition for 'url:ietf:params:xml:ns:xmpp-tls'.
54 */
55 #define XMPP_NS_TLS "urn:ietf:params:xml:ns:xmpp-tls"
56 /** @def XMPP_NS_SASL
57 * Namespace definition for 'urn:ietf:params:xml:ns:xmpp-sasl'.
58 */
59 #define XMPP_NS_SASL "urn:ietf:params:xml:ns:xmpp-sasl"
60 /** @def XMPP_NS_BIND
61 * Namespace definition for 'urn:ietf:params:xml:ns:xmpp-bind'.
62 */
63 #define XMPP_NS_BIND "urn:ietf:params:xml:ns:xmpp-bind"
64 /** @def XMPP_NS_SESSION
65 * Namespace definition for 'urn:ietf:params:xml:ns:xmpp-session'.
66 */
67 #define XMPP_NS_SESSION "urn:ietf:params:xml:ns:xmpp-session"
68 /** @def XMPP_NS_AUTH
69 * Namespace definition for 'jabber:iq:auth'.
70 */
71 #define XMPP_NS_AUTH "jabber:iq:auth"
72 /** @def XMPP_NS_DISCO_INFO
73 * Namespace definition for 'http://jabber.org/protocol/disco#info'.
74 */
75 #define XMPP_NS_DISCO_INFO "http://jabber.org/protocol/disco#info"
76 /** @def XMPP_NS_DISCO_ITEMS
77 * Namespace definition for 'http://jabber.org/protocol/disco#items'.
78 */
79 #define XMPP_NS_DISCO_ITEMS "http://jabber.org/protocol/disco#items"
80 /** @def XMPP_NS_ROSTER
81 * Namespace definition for 'jabber:iq:roster'.
82 */
83 #define XMPP_NS_ROSTER "jabber:iq:roster"
84
85 /* error defines */
86 /** @def XMPP_EOK
87 * Success error code.
88 */
89 #define XMPP_EOK 0
90 /** @def XMPP_EMEM
91 * Memory related failure error code.
92 *
93 * This is returned on allocation errors and signals that the host may
94 * be out of memory.
95 */
96 #define XMPP_EMEM -1
97 /** @def XMPP_EINVOP
98 * Invalid operation error code.
99 *
100 * This error code is returned when the operation was invalid and signals
101 * that the Strophe API is being used incorrectly.
102 */
103 #define XMPP_EINVOP -2
104 /** @def XMPP_EINT
105 * Internal failure error code.
106 */
107 #define XMPP_EINT -3
108
109 /* initialization and shutdown */
110 void LIBSTROPHE_EXPORTABLE xmpp_initialize();
111 void LIBSTROPHE_EXPORTABLE xmpp_shutdown();
112
113 /* version */
114 int LIBSTROPHE_EXPORTABLE xmpp_version_check(int major, int minor);
115
116 /* run-time contexts */
117
118 /* user-replaceable memory allocator */
119 typedef struct _xmpp_mem_t xmpp_mem_t;
120
121 /* user-replaceable log object */
122 typedef struct _xmpp_log_t xmpp_log_t;
123
124 /* opaque run time context containing the above hooks */
125 typedef struct _xmpp_ctx_t xmpp_ctx_t;
126
127 xmpp_ctx_t LIBSTROPHE_EXPORTABLE *xmpp_ctx_new(const xmpp_mem_t * const mem,
128 const xmpp_log_t * const log);
129 void LIBSTROPHE_EXPORTABLE xmpp_ctx_free(xmpp_ctx_t * const ctx);
130
131 /* free some blocks returned by other APIs, for example the
132 buffer you get from xmpp_stanza_to_text */
133 void LIBSTROPHE_EXPORTABLE xmpp_free(const xmpp_ctx_t * const ctx, void *p);
134
135 struct _xmpp_mem_t {
136 void *(*alloc)(const size_t size, void * const userdata);
137 void (*free)(void *p, void * const userdata);
138 void *(*realloc)(void *p, const size_t size, void * const userdata);
139 void *userdata;
140 };
141
142 typedef enum {
143 XMPP_LEVEL_DEBUG,
144 XMPP_LEVEL_INFO,
145 XMPP_LEVEL_WARN,
146 XMPP_LEVEL_ERROR
147 } xmpp_log_level_t;
148
149 typedef enum {
150 XMPP_UNKNOWN,
151 XMPP_CLIENT,
152 XMPP_COMPONENT
153 } xmpp_conn_type_t;
154
155 typedef void (*xmpp_log_handler)(void * const userdata,
156 const xmpp_log_level_t level,
157 const char * const area,
158 const char * const msg);
159
160 struct _xmpp_log_t {
161 xmpp_log_handler handler;
162 void *userdata;
163 };
164
165 /* return a default logger filtering at a given level */
166 xmpp_log_t LIBSTROPHE_EXPORTABLE *xmpp_get_default_logger(xmpp_log_level_t level);
167
168 /* connection */
169
170 typedef enum {
171 XMPP_LOOP_NOTSTARTED,
172 XMPP_LOOP_RUNNING,
173 XMPP_LOOP_QUIT
174 } xmpp_loop_status_t;
175
176 /* opaque connection object */
177 typedef struct _xmpp_conn_t xmpp_conn_t;
178 typedef struct _xmpp_stanza_t xmpp_stanza_t;
179
180 /* connection flags */
181 #define XMPP_CONN_FLAG_DISABLE_TLS (1UL << 0)
182 #define XMPP_CONN_FLAG_MANDATORY_TLS (1UL << 1)
183 #define XMPP_CONN_FLAG_LEGACY_SSL (1UL << 2)
184
185 /* connect callback */
186 typedef enum {
187 XMPP_CONN_CONNECT,
188 XMPP_CONN_RAW_CONNECT,
189 XMPP_CONN_DISCONNECT,
190 XMPP_CONN_FAIL
191 } xmpp_conn_event_t;
192
193 typedef enum {
194 XMPP_SE_BAD_FORMAT,
195 XMPP_SE_BAD_NS_PREFIX,
196 XMPP_SE_CONFLICT,
197 XMPP_SE_CONN_TIMEOUT,
198 XMPP_SE_HOST_GONE,
199 XMPP_SE_HOST_UNKNOWN,
200 XMPP_SE_IMPROPER_ADDR,
201 XMPP_SE_INTERNAL_SERVER_ERROR,
202 XMPP_SE_INVALID_FROM,
203 XMPP_SE_INVALID_ID,
204 XMPP_SE_INVALID_NS,
205 XMPP_SE_INVALID_XML,
206 XMPP_SE_NOT_AUTHORIZED,
207 XMPP_SE_POLICY_VIOLATION,
208 XMPP_SE_REMOTE_CONN_FAILED,
209 XMPP_SE_RESOURCE_CONSTRAINT,
210 XMPP_SE_RESTRICTED_XML,
211 XMPP_SE_SEE_OTHER_HOST,
212 XMPP_SE_SYSTEM_SHUTDOWN,
213 XMPP_SE_UNDEFINED_CONDITION,
214 XMPP_SE_UNSUPPORTED_ENCODING,
215 XMPP_SE_UNSUPPORTED_STANZA_TYPE,
216 XMPP_SE_UNSUPPORTED_VERSION,
217 XMPP_SE_XML_NOT_WELL_FORMED
218 } xmpp_error_type_t;
219
220 typedef struct {
221 xmpp_error_type_t type;
222 char *text;
223 xmpp_stanza_t *stanza;
224 } xmpp_stream_error_t;
225
226 typedef void (*xmpp_conn_handler)(xmpp_conn_t * const conn,
227 const xmpp_conn_event_t event,
228 const int error,
229 xmpp_stream_error_t * const stream_error,
230 void * const userdata);
231
232 xmpp_conn_t LIBSTROPHE_EXPORTABLE *xmpp_conn_new(xmpp_ctx_t * const ctx);
233 xmpp_conn_t LIBSTROPHE_EXPORTABLE *xmpp_conn_clone(xmpp_conn_t * const conn);
234 int LIBSTROPHE_EXPORTABLE xmpp_conn_release(xmpp_conn_t * const conn);
235
236 long LIBSTROPHE_EXPORTABLE xmpp_conn_get_flags(const xmpp_conn_t * const conn);
237 int LIBSTROPHE_EXPORTABLE xmpp_conn_set_flags(xmpp_conn_t * const conn, long flags);
238 const char LIBSTROPHE_EXPORTABLE *xmpp_conn_get_jid(const xmpp_conn_t * const conn);
239 const char LIBSTROPHE_EXPORTABLE *xmpp_conn_get_bound_jid(const xmpp_conn_t * const conn);
240 void LIBSTROPHE_EXPORTABLE xmpp_conn_set_jid(xmpp_conn_t * const conn, const char * const jid);
241 const char LIBSTROPHE_EXPORTABLE *xmpp_conn_get_pass(const xmpp_conn_t * const conn);
242 void LIBSTROPHE_EXPORTABLE xmpp_conn_set_pass(xmpp_conn_t * const conn, const char * const pass);
243 xmpp_ctx_t LIBSTROPHE_EXPORTABLE *xmpp_conn_get_context(xmpp_conn_t * const conn);
244 void LIBSTROPHE_EXPORTABLE xmpp_conn_disable_tls(xmpp_conn_t * const conn);
245 int LIBSTROPHE_EXPORTABLE xmpp_conn_is_secured(xmpp_conn_t * const conn);
246 void LIBSTROPHE_EXPORTABLE xmpp_conn_set_keepalive(xmpp_conn_t * const conn, int timeout, int interval);
247
248 int LIBSTROPHE_EXPORTABLE xmpp_connect_client(xmpp_conn_t * const conn,
249 const char * const altdomain,
250 unsigned short altport,
251 xmpp_conn_handler callback,
252 void * const userdata);
253
254 int LIBSTROPHE_EXPORTABLE xmpp_connect_component(xmpp_conn_t * const conn, const char * const server,
255 unsigned short port, xmpp_conn_handler callback,
256 void * const userdata);
257
258 int LIBSTROPHE_EXPORTABLE xmpp_connect_raw(xmpp_conn_t * const conn,
259 const char * const altdomain,
260 unsigned short altport,
261 xmpp_conn_handler callback,
262 void * const userdata);
263 int LIBSTROPHE_EXPORTABLE xmpp_conn_open_stream_default(xmpp_conn_t * const conn);
264 int LIBSTROPHE_EXPORTABLE xmpp_conn_open_stream(xmpp_conn_t * const conn, char **attributes,
265 size_t attributes_len);
266 int LIBSTROPHE_EXPORTABLE xmpp_conn_tls_start(xmpp_conn_t * const conn);
267
268 void LIBSTROPHE_EXPORTABLE xmpp_disconnect(xmpp_conn_t * const conn);
269
270 void LIBSTROPHE_EXPORTABLE xmpp_send(xmpp_conn_t * const conn,
271 xmpp_stanza_t * const stanza);
272
273 void LIBSTROPHE_EXPORTABLE xmpp_send_raw_string(xmpp_conn_t * const conn,
274 const char * const fmt, ...);
275 void LIBSTROPHE_EXPORTABLE xmpp_send_raw(xmpp_conn_t * const conn,
276 const char * const data, const size_t len);
277
278
279 /* handlers */
280
281 /* if the handle returns false it is removed */
282 typedef int (*xmpp_timed_handler)(xmpp_conn_t * const conn,
283 void * const userdata);
284
285 void LIBSTROPHE_EXPORTABLE xmpp_timed_handler_add(xmpp_conn_t * const conn,
286 xmpp_timed_handler handler,
287 const unsigned long period,
288 void * const userdata);
289 void LIBSTROPHE_EXPORTABLE xmpp_timed_handler_delete(xmpp_conn_t * const conn,
290 xmpp_timed_handler handler);
291
292
293 /* if the handler returns false it is removed */
294 typedef int (*xmpp_handler)(xmpp_conn_t * const conn,
295 xmpp_stanza_t * const stanza,
296 void * const userdata);
297
298 void LIBSTROPHE_EXPORTABLE xmpp_handler_add(xmpp_conn_t * const conn,
299 xmpp_handler handler,
300 const char * const ns,
301 const char * const name,
302 const char * const type,
303 void * const userdata);
304 void LIBSTROPHE_EXPORTABLE xmpp_handler_delete(xmpp_conn_t * const conn,
305 xmpp_handler handler);
306
307 void LIBSTROPHE_EXPORTABLE xmpp_id_handler_add(xmpp_conn_t * const conn,
308 xmpp_handler handler,
309 const char * const id,
310 void * const userdata);
311 void LIBSTROPHE_EXPORTABLE xmpp_id_handler_delete(xmpp_conn_t * const conn,
312 xmpp_handler handler,
313 const char * const id);
314
315 /*
316 void xmpp_register_stanza_handler(conn, stanza, xmlns, type, handler)
317 */
318
319 /* stanzas */
320
321 /* allocate and initialize a blank stanza */
322 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_stanza_new(xmpp_ctx_t *ctx);
323
324 /* clone a stanza */
325 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_stanza_clone(xmpp_stanza_t * const stanza);
326
327 /* copies a stanza and all children */
328 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_stanza_copy(const xmpp_stanza_t * const stanza);
329
330 /* free a stanza object and it's contents */
331 int LIBSTROPHE_EXPORTABLE xmpp_stanza_release(xmpp_stanza_t * const stanza);
332
333 int LIBSTROPHE_EXPORTABLE xmpp_stanza_is_text(xmpp_stanza_t * const stanza);
334 int LIBSTROPHE_EXPORTABLE xmpp_stanza_is_tag(xmpp_stanza_t * const stanza);
335
336 /* marshall a stanza into text for transmission or display */
337 int LIBSTROPHE_EXPORTABLE xmpp_stanza_to_text(xmpp_stanza_t *stanza,
338 char ** const buf, size_t * const buflen);
339
340 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_children(xmpp_stanza_t * const stanza);
341 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_child_by_name(xmpp_stanza_t * const stanza,
342 const char * const name);
343 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_child_by_ns(xmpp_stanza_t * const stanza,
344 const char * const ns);
345 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_next(xmpp_stanza_t * const stanza);
346 int LIBSTROPHE_EXPORTABLE xmpp_stanza_add_child(xmpp_stanza_t *stanza, xmpp_stanza_t *child);
347 int LIBSTROPHE_EXPORTABLE xmpp_stanza_add_child_ex(xmpp_stanza_t *stanza, xmpp_stanza_t *child, int do_clone);
348
349 const char LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_attribute(xmpp_stanza_t * const stanza,
350 const char * const name);
351 int LIBSTROPHE_EXPORTABLE xmpp_stanza_get_attribute_count(xmpp_stanza_t * const stanza);
352 int LIBSTROPHE_EXPORTABLE xmpp_stanza_get_attributes(xmpp_stanza_t * const stanza,
353 const char **attr, int attrlen);
354 /* concatenate all child text nodes. this function
355 * returns a string that must be freed by the caller */
356 char LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_text(xmpp_stanza_t * const stanza);
357 const char LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_text_ptr(xmpp_stanza_t * const stanza);
358 const char LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_name(xmpp_stanza_t * const stanza);
359 /* set_attribute adds/replaces attributes */
360 int LIBSTROPHE_EXPORTABLE xmpp_stanza_set_attribute(xmpp_stanza_t * const stanza,
361 const char * const key,
362 const char * const value);
363 int LIBSTROPHE_EXPORTABLE xmpp_stanza_set_name(xmpp_stanza_t *stanza,
364 const char * const name);
365 int LIBSTROPHE_EXPORTABLE xmpp_stanza_set_text(xmpp_stanza_t *stanza,
366 const char * const text);
367 int LIBSTROPHE_EXPORTABLE xmpp_stanza_set_text_with_size(xmpp_stanza_t *stanza,
368 const char * const text,
369 const size_t size);
370 int LIBSTROPHE_EXPORTABLE xmpp_stanza_del_attribute(xmpp_stanza_t * const stanza,
371 const char * const name);
372
373 /* common stanza helpers */
374 const char LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_ns(xmpp_stanza_t * const stanza);
375 const char LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_type(xmpp_stanza_t * const stanza);
376 const char LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_id(xmpp_stanza_t * const stanza);
377 const char LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_to(xmpp_stanza_t * const stanza);
378 const char LIBSTROPHE_EXPORTABLE *xmpp_stanza_get_from(xmpp_stanza_t * const stanza);
379 int LIBSTROPHE_EXPORTABLE xmpp_stanza_set_ns(xmpp_stanza_t * const stanza, const char * const ns);
380 int LIBSTROPHE_EXPORTABLE xmpp_stanza_set_id(xmpp_stanza_t * const stanza, const char * const id);
381 int LIBSTROPHE_EXPORTABLE xmpp_stanza_set_type(xmpp_stanza_t * const stanza, const char * const type);
382 int LIBSTROPHE_EXPORTABLE xmpp_stanza_set_to(xmpp_stanza_t * const stanza, const char * const to);
383 int LIBSTROPHE_EXPORTABLE xmpp_stanza_set_from(xmpp_stanza_t * const stanza, const char * const from);
384
385 /* allocate and initialize a stanza in reply to another */
386 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_stanza_reply(xmpp_stanza_t * const stanza);
387
388 /* stanza subclasses */
389 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_message_new(xmpp_ctx_t *ctx, const char * const type,
390 const char * const to, const char * const id);
391 char LIBSTROPHE_EXPORTABLE *xmpp_message_get_body(xmpp_stanza_t *msg);
392 int LIBSTROPHE_EXPORTABLE xmpp_message_set_body(xmpp_stanza_t *msg, const char * const text);
393
394 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_iq_new(xmpp_ctx_t *ctx, const char * const type,
395 const char * const id);
396 xmpp_stanza_t LIBSTROPHE_EXPORTABLE *xmpp_presence_new(xmpp_ctx_t *ctx);
397
398 /* jid */
399
400 /* these return new strings that must be xmpp_free()'d */
401 char LIBSTROPHE_EXPORTABLE *xmpp_jid_new(xmpp_ctx_t *ctx, const char *node,
402 const char *domain,
403 const char *resource);
404 char LIBSTROPHE_EXPORTABLE *xmpp_jid_bare(xmpp_ctx_t *ctx, const char *jid);
405 char LIBSTROPHE_EXPORTABLE *xmpp_jid_node(xmpp_ctx_t *ctx, const char *jid);
406 char LIBSTROPHE_EXPORTABLE *xmpp_jid_domain(xmpp_ctx_t *ctx, const char *jid);
407 char LIBSTROPHE_EXPORTABLE *xmpp_jid_resource(xmpp_ctx_t *ctx, const char *jid);
408
409 /* event loop */
410
411 void LIBSTROPHE_EXPORTABLE xmpp_run_once(xmpp_ctx_t *ctx, const unsigned long timeout);
412 void LIBSTROPHE_EXPORTABLE xmpp_run(xmpp_ctx_t *ctx);
413 void LIBSTROPHE_EXPORTABLE xmpp_stop(xmpp_ctx_t *ctx);
414
415 /* UUID */
416
417 char LIBSTROPHE_EXPORTABLE *xmpp_uuid_gen(xmpp_ctx_t *ctx);
418
419 /* SHA1 */
420
421 /** @def XMPP_SHA1_DIGEST_SIZE
422 * Size of the SHA1 message digest.
423 */
424 #define XMPP_SHA1_DIGEST_SIZE 20
425
426 typedef struct _xmpp_sha1_t xmpp_sha1_t;
427
428 char *xmpp_sha1(xmpp_ctx_t *ctx, const unsigned char *data, size_t len);
429
430 xmpp_sha1_t LIBSTROPHE_EXPORTABLE *xmpp_sha1_new(xmpp_ctx_t *ctx);
431 void LIBSTROPHE_EXPORTABLE xmpp_sha1_free(xmpp_sha1_t *sha1);
432 void LIBSTROPHE_EXPORTABLE xmpp_sha1_update(xmpp_sha1_t *sha1, const unsigned char *data, size_t len);
433 void LIBSTROPHE_EXPORTABLE xmpp_sha1_final(xmpp_sha1_t *sha1);
434 char LIBSTROPHE_EXPORTABLE *xmpp_sha1_to_string(xmpp_sha1_t *sha1, char *s, size_t slen);
435 char LIBSTROPHE_EXPORTABLE *xmpp_sha1_to_string_alloc(xmpp_sha1_t *sha1);
436 void LIBSTROPHE_EXPORTABLE xmpp_sha1_to_digest(xmpp_sha1_t *sha1, unsigned char *digest);
437
438 /* Base64 */
439
440 char LIBSTROPHE_EXPORTABLE *xmpp_base64_encode(xmpp_ctx_t *ctx, const unsigned char *data, size_t len);
441 char LIBSTROPHE_EXPORTABLE *xmpp_base64_decode_str(xmpp_ctx_t *ctx, const char *base64, size_t len);
442 void LIBSTROPHE_EXPORTABLE xmpp_base64_decode_bin(xmpp_ctx_t *ctx, const char *base64, size_t len,
443 unsigned char **out, size_t *outlen);
444
445 void LIBSTROPHE_EXPORTABLE xmpp_set_loop_status(xmpp_ctx_t *ctx, xmpp_loop_status_t status);
446 xmpp_loop_status_t LIBSTROPHE_EXPORTABLE xmpp_get_loop_status(xmpp_ctx_t *ctx);
447
448 #ifdef __cplusplus
449 }
450 #endif
451
452 #endif /* __LIBSTROPHE_STROPHE_H__ */