libstrophe/bindings.d

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