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