libpurple/protocols/facebook/mqtt.h

   1 /* purple
   2  *
   3  * Purple is the legal property of its developers, whose names are too numerous
   4  * to list here.  Please refer to the COPYRIGHT file distributed with this
   5  * source distribution.
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  20  */
  21
  22 #ifndef PURPLE_FACEBOOK_MQTT_H
  23 #define PURPLE_FACEBOOK_MQTT_H
  24
  25 /**
  26  * SECTION:mqtt
  27  * @section_id: facebook-mqtt
  28  * @short_description: <filename>mqtt.h</filename>
  29  * @title: MQTT Connection
  30  *
  31  * The MQTT connection.
  32  */
  33
  34 #include <glib.h>
  35 #include <string.h>
  36
  37 #include "connection.h"
  38
  39 #define FB_TYPE_MQTT  fb_mqtt_get_type()
  40 #define FB_TYPE_MQTT_MESSAGE  fb_mqtt_message_get_type()
  41
  42 /**
  43  * FB_MQTT_NAME:
  44  *
  45  * The name of the MQTT version.
  46  */
  47 #define FB_MQTT_NAME  "MQTToT"
  48
  49 /**
  50  * FB_MQTT_LEVEL:
  51  *
  52  * The level of the MQTT version.
  53  */
  54 #define FB_MQTT_LEVEL  3
  55
  56 /**
  57  * FB_MQTT_KA:
  58  *
  59  * The keep-alive timeout, in seconds, of the MQTT connection.
  60  */
  61 #define FB_MQTT_KA  60
  62
  63 /**
  64  * FB_MQTT_HOST:
  65  *
  66  * The MQTT host name for Facebook.
  67  */
  68 #define FB_MQTT_HOST  "mqtt.facebook.com"
  69
  70 /**
  71  * FB_MQTT_PORT:
  72  *
  73  * The MQTT host port for Facebook.
  74  */
  75 #define FB_MQTT_PORT  443
  76
  77 /**
  78  * FB_MQTT_TIMEOUT_CONN:
  79  *
  80  * The timeout, in milliseconds, to wait for a PING back from the
  81  * server.
  82  */
  83 #define FB_MQTT_TIMEOUT_CONN  (FB_MQTT_KA * 1500)
  84
  85 /**
  86  * FB_MQTT_TIMEOUT_PING:
  87  *
  88  * The timeout, in milliseconds, to send a PING to the server.
  89  */
  90 #define FB_MQTT_TIMEOUT_PING  (FB_MQTT_KA * 1000)
  91
  92 /**
  93  * FB_MQTT_ERROR:
  94  *
  95  * The #GQuark of the domain of MQTT errors.
  96  */
  97 #define FB_MQTT_ERROR  fb_mqtt_error_quark()
  98
  99 /**
 100  * FbMqttConnectFlags:
 101  * @FB_MQTT_CONNECT_FLAG_CLR: Clear the session.
 102  * @FB_MQTT_CONNECT_FLAG_WILL: A will message is in the payload.
 103  * @FB_MQTT_CONNECT_FLAG_RET: Retain the will message.
 104  * @FB_MQTT_CONNECT_FLAG_PASS: A password is in the payload.
 105  * @FB_MQTT_CONNECT_FLAG_USER: A user name is in the payload.
 106  * @FB_MQTT_CONNECT_FLAG_QOS0: Use no quality of service.
 107  * @FB_MQTT_CONNECT_FLAG_QOS1: Use level one quality of service.
 108  * @FB_MQTT_CONNECT_FLAG_QOS2: Use level two quality of service.
 109  *
 110  * The #FbMqttMessage flags for the CONNECT message.
 111  */
 112 typedef enum
 113 {
 114         FB_MQTT_CONNECT_FLAG_CLR = 1 << 1,
 115         FB_MQTT_CONNECT_FLAG_WILL = 1 << 2,
 116         FB_MQTT_CONNECT_FLAG_RET = 1 << 5,
 117         FB_MQTT_CONNECT_FLAG_PASS = 1 << 6,
 118         FB_MQTT_CONNECT_FLAG_USER = 1 << 7,
 119         FB_MQTT_CONNECT_FLAG_QOS0 = 0 << 3,
 120         FB_MQTT_CONNECT_FLAG_QOS1 = 1 << 3,
 121         FB_MQTT_CONNECT_FLAG_QOS2 = 2 << 3
 122 } FbMqttConnectFlags;
 123
 124 /**
 125  * FbMqttError:
 126  * @FB_MQTT_ERROR_SUCCESS: There is no error.
 127  * @FB_MQTT_ERROR_PRTVERS: Unacceptable protocol version.
 128  * @FB_MQTT_ERROR_IDREJECT: Identifier rejected.
 129  * @FB_MQTT_ERROR_SRVGONE: Server unavailable.
 130  * @FB_MQTT_ERROR_USERPASS: Bad user name or password.
 131  * @FB_MQTT_ERROR_UNAUTHORIZED: Not authorized.
 132  * @FB_MQTT_ERROR_GENERAL: General failure.
 133  *
 134  * The error codes for the #FB_MQTT_ERROR domain.
 135  */
 136 typedef enum
 137 {
 138         FB_MQTT_ERROR_SUCCESS = 0,
 139         FB_MQTT_ERROR_PRTVERS = 1,
 140         FB_MQTT_ERROR_IDREJECT = 2,
 141         FB_MQTT_ERROR_SRVGONE = 3,
 142         FB_MQTT_ERROR_USERPASS = 4,
 143         FB_MQTT_ERROR_UNAUTHORIZED = 5,
 144         FB_MQTT_ERROR_GENERAL
 145 } FbMqttError;
 146
 147 /**
 148  * FbMqttMessageFlags:
 149  * @FB_MQTT_MESSAGE_FLAG_RET: Retain messages.
 150  * @FB_MQTT_MESSAGE_FLAG_DUP: Duplicate delivery of control packet.
 151  * @FB_MQTT_MESSAGE_FLAG_QOS0: Use no quality of service.
 152  * @FB_MQTT_MESSAGE_FLAG_QOS1: Use level one quality of service.
 153  * @FB_MQTT_MESSAGE_FLAG_QOS2: Use level two quality of service.
 154  *
 155  * The #FbMqttMessage flags.
 156  */
 157 typedef enum
 158 {
 159         FB_MQTT_MESSAGE_FLAG_RET = 1 << 0,
 160         FB_MQTT_MESSAGE_FLAG_DUP = 1 << 3,
 161         FB_MQTT_MESSAGE_FLAG_QOS0 = 0 << 1,
 162         FB_MQTT_MESSAGE_FLAG_QOS1 = 1 << 1,
 163         FB_MQTT_MESSAGE_FLAG_QOS2 = 2 << 1
 164 } FbMqttMessageFlags;
 165
 166 /**
 167  * FbMqttMessageType:
 168  * @FB_MQTT_MESSAGE_TYPE_CONNECT: Requests a connection.
 169  * @FB_MQTT_MESSAGE_TYPE_CONNACK: Connection acknowledgment.
 170  * @FB_MQTT_MESSAGE_TYPE_PUBLISH: Requests a message publication.
 171  * @FB_MQTT_MESSAGE_TYPE_PUBACK: Publication acknowledgment.
 172  * @FB_MQTT_MESSAGE_TYPE_PUBREC: Publication received.
 173  * @FB_MQTT_MESSAGE_TYPE_PUBREL: Publication released.
 174  * @FB_MQTT_MESSAGE_TYPE_PUBCOMP: Publication complete.
 175  * @FB_MQTT_MESSAGE_TYPE_SUBSCRIBE: Requests a subscription.
 176  * @FB_MQTT_MESSAGE_TYPE_SUBACK: Subscription acknowledgment.
 177  * @FB_MQTT_MESSAGE_TYPE_UNSUBSCRIBE: Requests an unsubscription.
 178  * @FB_MQTT_MESSAGE_TYPE_UNSUBACK: Unsubscription acknowledgment.
 179  * @FB_MQTT_MESSAGE_TYPE_PINGREQ: Requests a ping response.
 180  * @FB_MQTT_MESSAGE_TYPE_PINGRESP: Ping response.
 181  * @FB_MQTT_MESSAGE_TYPE_DISCONNECT: Requests a disconnection.
 182  *
 183  * The #FbMqttMessage types.
 184  */
 185 typedef enum
 186 {
 187         FB_MQTT_MESSAGE_TYPE_CONNECT = 1,
 188         FB_MQTT_MESSAGE_TYPE_CONNACK = 2,
 189         FB_MQTT_MESSAGE_TYPE_PUBLISH = 3,
 190         FB_MQTT_MESSAGE_TYPE_PUBACK = 4,
 191         FB_MQTT_MESSAGE_TYPE_PUBREC = 5,
 192         FB_MQTT_MESSAGE_TYPE_PUBREL = 6,
 193         FB_MQTT_MESSAGE_TYPE_PUBCOMP = 7,
 194         FB_MQTT_MESSAGE_TYPE_SUBSCRIBE = 8,
 195         FB_MQTT_MESSAGE_TYPE_SUBACK = 9,
 196         FB_MQTT_MESSAGE_TYPE_UNSUBSCRIBE = 10,
 197         FB_MQTT_MESSAGE_TYPE_UNSUBACK = 11,
 198         FB_MQTT_MESSAGE_TYPE_PINGREQ = 12,
 199         FB_MQTT_MESSAGE_TYPE_PINGRESP = 13,
 200         FB_MQTT_MESSAGE_TYPE_DISCONNECT = 14
 201 } FbMqttMessageType;
 202
 203 /**
 204  * fb_mqtt_get_type:
 205  *
 206  * Returns: The #GType for an #FbMqtt.
 207  */
 208 G_DECLARE_FINAL_TYPE(FbMqtt, fb_mqtt, FB, MQTT, GObject)
 209
 210 /**
 211  * fb_mqtt_message_get_type:
 212  *
 213  * Returns: The #GType for an #FbMqttMessage.
 214  */
 215 G_DECLARE_FINAL_TYPE(FbMqttMessage, fb_mqtt_message, FB, MQTT_MESSAGE,
 216                 GObject)
 217
 218 /**
 219  * fb_mqtt_error_quark:
 220  *
 221  * Gets the #GQuark of the domain of MQTT errors.
 222  *
 223  * Returns: The #GQuark of the domain.
 224  */
 225 GQuark
 226 fb_mqtt_error_quark(void);
 227
 228 /**
 229  * fb_mqtt_new:
 230  * @gc: The #PurpleConnection.
 231  *
 232  * Creates a new #FbMqtt. The returned #FbMqtt should be freed with
 233  * #g_object_unref() when no longer needed.
 234  *
 235  * Returns: The new #FbMqtt.
 236  */
 237 FbMqtt *
 238 fb_mqtt_new(PurpleConnection *gc);
 239
 240 /**
 241  * fb_mqtt_close:
 242  * @mqtt: The #FbMqtt.
 243  *
 244  * Closes the MQTT without sending the `DISCONNECT` message. The #FbMqtt
 245  * may be reopened after calling this.
 246  */
 247 void
 248 fb_mqtt_close(FbMqtt *mqtt);
 249
 250 /**
 251  * fb_mqtt_error:
 252  * @mqtt: The #FbMqtt.
 253  * @error: The #FbMqttError.
 254  * @format: The format string literal.
 255  * @...: The arguments for @format.
 256  *
 257  * Emits an #FbMqttError and closes the #FbMqtt.
 258  */
 259 void
 260 fb_mqtt_error(FbMqtt *mqtt, FbMqttError error, const gchar *format, ...)
 261               G_GNUC_PRINTF(3, 4);
 262
 263 /**
 264  * fb_mqtt_read:
 265  * @mqtt: The #FbMqtt.
 266  * @msg: The #FbMqttMessage.
 267  *
 268  * Reads an #FbMqttMessage into the #FbMqtt for processing.
 269  */
 270 void
 271 fb_mqtt_read(FbMqtt *mqtt, FbMqttMessage *msg);
 272
 273 /**
 274  * fb_mqtt_write:
 275  * @mqtt: The #FbMqtt.
 276  * @msg: The #FbMqttMessage.
 277  *
 278  * Writes an #FbMqttMessage to the wire.
 279  */
 280 void
 281 fb_mqtt_write(FbMqtt *mqtt, FbMqttMessage *msg);
 282
 283 /**
 284  * fb_mqtt_open:
 285  * @mqtt: The #FbMqtt.
 286  * @host: The host name.
 287  * @port: The port.
 288  *
 289  * Opens an SSL connection to the remote server.
 290  */
 291 void
 292 fb_mqtt_open(FbMqtt *mqtt, const gchar *host, gint port);
 293
 294 /**
 295  * fb_mqtt_connect:
 296  * @mqtt: The #FbMqtt.
 297  * @flags: The #FbMqttConnectFlags.
 298  * @pload: The payload.
 299  *
 300  * Sends a message of type #FB_MQTT_MESSAGE_TYPE_CONNECT.
 301  */
 302 void
 303 fb_mqtt_connect(FbMqtt *mqtt, guint8 flags, const GByteArray *pload);
 304
 305 /**
 306  * fb_mqtt_connected:
 307  * @mqtt: The #FbMqtt.
 308  * @error: #TRUE to error with no connection, otherwise #FALSE.
 309  *
 310  * Determines the connection state of the #FbMqtt, and optionally emits
 311  * an error.
 312  *
 313  * Returns: #TRUE if the #FbMqtt is connected, otherwise #FALSE.
 314  */
 315 gboolean
 316 fb_mqtt_connected(FbMqtt *mqtt, gboolean error);
 317
 318 /**
 319  * fb_mqtt_disconnect:
 320  * @mqtt: The #FbMqtt.
 321  *
 322  * Sends a message of type #FB_MQTT_MESSAGE_TYPE_DISCONNECT, and closes
 323  * the connection.
 324  */
 325 void
 326 fb_mqtt_disconnect(FbMqtt *mqtt);
 327
 328 /**
 329  * fb_mqtt_publish:
 330  * @mqtt: The #FbMqtt.
 331  * @topic: The topic.
 332  * @pload: The payload.
 333  *
 334  * Sends a message of type #FB_MQTT_MESSAGE_TYPE_PUBLISH.
 335  */
 336 void
 337 fb_mqtt_publish(FbMqtt *mqtt, const gchar *topic, const GByteArray *pload);
 338
 339 /**
 340  * fb_mqtt_subscribe:
 341  * @mqtt: The #FbMqtt.
 342  * @topic1: The first topic.
 343  * @qos1: The first QoS.
 344  * @...: The %NULL-terminated list of topic/QoS pairs.
 345  *
 346  * Sends a message of type #FB_MQTT_MESSAGE_TYPE_SUBSCRIBE.
 347  */
 348 void
 349 fb_mqtt_subscribe(FbMqtt *mqtt, const gchar *topic1, guint16 qos1, ...)
 350                   G_GNUC_NULL_TERMINATED;
 351
 352 /**
 353  * fb_mqtt_unsubscribe:
 354  * @mqtt: The #FbMqtt.
 355  * @topic1: The first topic.
 356  * @...: The %NULL-terminated list of topics.
 357  *
 358  * Sends a message of type #FB_MQTT_MESSAGE_TYPE_UNSUBSCRIBE.
 359  */
 360 void
 361 fb_mqtt_unsubscribe(FbMqtt *mqtt, const gchar *topic1, ...)
 362                     G_GNUC_NULL_TERMINATED;
 363
 364 /**
 365  * fb_mqtt_message_new:
 366  * @type: The #FbMqttMessageType.
 367  * @flags: The #FbMqttMessageFlags.
 368  *
 369  * Creates a new #FbMqttMessage. The returned #FbMqttMessage should be
 370  * freed with #g_object_unref() when no longer needed.
 371  *
 372  * Returns: The new #FbMqttMessage.
 373  */
 374 FbMqttMessage *
 375 fb_mqtt_message_new(FbMqttMessageType type, FbMqttMessageFlags flags);
 376
 377 /**
 378  * fb_mqtt_message_new_bytes:
 379  * @bytes: The #GByteArray.
 380  *
 381  * Creates a new #FbMqttMessage from a #GByteArray. The returned
 382  * #FbMqttMessage should be freed with #g_object_unref() when no
 383  * longer needed.
 384  *
 385  * Returns: The new #FbMqttMessage.
 386  */
 387 FbMqttMessage *
 388 fb_mqtt_message_new_bytes(GByteArray *bytes);
 389
 390 /**
 391  * fb_mqtt_message_reset:
 392  * @msg: The #FbMqttMessage.
 393  *
 394  * Resets an #FbMqttMessage. This resets the cursor position, and
 395  * removes any sort of fixed header.
 396  */
 397 void
 398 fb_mqtt_message_reset(FbMqttMessage *msg);
 399
 400 /**
 401  * fb_mqtt_message_bytes:
 402  * @msg: The #FbMqttMessage.
 403  *
 404  * Formats the internal #GByteArray of the #FbMqttMessage with the
 405  * required fixed header. This resets the cursor position.
 406  *
 407  * Returns: The internal #GByteArray.
 408  */
 409 const GByteArray *
 410 fb_mqtt_message_bytes(FbMqttMessage *msg);
 411
 412 /**
 413  * fb_mqtt_message_read:
 414  * @msg: The #FbMqttMessage.
 415  * @data: The data buffer.
 416  * @size: The size of @buffer.
 417  *
 418  * Reads data from the #FbMqttMessage into a buffer. If @data is #NULL,
 419  * this will simply advance the cursor position.
 420  *
 421  * Returns: #TRUE if the data was read, otherwise #FALSE.
 422  */
 423 gboolean
 424 fb_mqtt_message_read(FbMqttMessage *msg, gpointer data, guint size);
 425
 426 /**
 427  * fb_mqtt_message_read_r:
 428  * @msg: The #FbMqttMessage.
 429  * @bytes: The #GByteArray.
 430  *
 431  * Reads the remaining data from the #FbMqttMessage into a #GByteArray.
 432  * This is useful for obtaining the payload of a message.
 433  *
 434  * Returns: #TRUE if the data was read, otherwise #FALSE.
 435  */
 436 gboolean
 437 fb_mqtt_message_read_r(FbMqttMessage *msg, GByteArray *bytes);
 438
 439 /**
 440  * fb_mqtt_message_read_byte:
 441  * @msg: The #FbMqttMessage.
 442  * @value: The return location for the value or #NULL.
 443  *
 444  * Reads an 8-bit integer value from the #FbMqttMessage. If @value is
 445  * #NULL, this will simply advance the cursor position.
 446  *
 447  * Returns: #TRUE if the value was read, otherwise #FALSE.
 448  */
 449 gboolean
 450 fb_mqtt_message_read_byte(FbMqttMessage *msg, guint8 *value);
 451
 452 /**
 453  * fb_mqtt_message_read_mid:
 454  * @msg: The #FbMqttMessage.
 455  * @value: The return location for the value or #NULL.
 456  *
 457  * Reads a message identifier from the #FbMqttMessage. If @value is
 458  * #NULL, this will simply advance the cursor position.
 459  *
 460  * Returns: #TRUE if the value was read, otherwise #FALSE.
 461  */
 462 gboolean
 463 fb_mqtt_message_read_mid(FbMqttMessage *msg, guint16 *value);
 464
 465 /**
 466  * fb_mqtt_message_read_u16:
 467  * @msg: The #FbMqttMessage.
 468  * @value: The return location for the value or #NULL.
 469  *
 470  * Reads a 16-bit integer value from the #FbMqttMessage. If @value is
 471  * #NULL, this will simply advance the cursor position.
 472  *
 473  * Returns: #TRUE if the value was read, otherwise #FALSE.
 474  */
 475 gboolean
 476 fb_mqtt_message_read_u16(FbMqttMessage *msg, guint16 *value);
 477
 478 /**
 479  * fb_mqtt_message_read_str:
 480  * @msg: The #FbMqttMessage.
 481  * @value: The return location for the value or #NULL.
 482  *
 483  * Reads a string value from the #FbMqttMessage. The value returned to
 484  * @value should be freed with #g_free() when no longer needed. If
 485  * @value is #NULL, this will simply advance the cursor position.
 486  *
 487  * Returns: #TRUE if the value was read, otherwise #FALSE.
 488  */
 489 gboolean
 490 fb_mqtt_message_read_str(FbMqttMessage *msg, gchar **value);
 491
 492 /**
 493  * fb_mqtt_message_write:
 494  * @msg: The #FbMqttMessage.
 495  * @data: The data buffer.
 496  * @size: The size of @buffer.
 497  *
 498  * Writes data to the #FbMqttMessage.
 499  */
 500 void
 501 fb_mqtt_message_write(FbMqttMessage *msg, gconstpointer data, guint size);
 502
 503 /**
 504  * fb_mqtt_message_write_byte:
 505  * @msg: The #FbMqttMessage.
 506  * @value: The value.
 507  *
 508  * Writes an 8-bit integer value to the #FbMqttMessage.
 509  */
 510 void
 511 fb_mqtt_message_write_byte(FbMqttMessage *msg, guint8 value);
 512
 513 /**
 514  * fb_mqtt_message_write_mid:
 515  * @msg: The #FbMqttMessage.
 516  * @value: The value.
 517  *
 518  * Writes a message identifier to the #FbMqttMessage. This increments
 519  * @value for the next message.
 520  */
 521 void
 522 fb_mqtt_message_write_mid(FbMqttMessage *msg, guint16 *value);
 523
 524 /**
 525  * fb_mqtt_message_write_u16:
 526  * @msg: The #FbMqttMessage.
 527  * @value: The value.
 528  *
 529  * Writes a 16-bit integer value to the #FbMqttMessage.
 530  */
 531 void
 532 fb_mqtt_message_write_u16(FbMqttMessage *msg, guint16 value);
 533
 534 /**
 535  * fb_mqtt_message_write_str:
 536  * @msg: The #FbMqttMessage.
 537  * @value: The value.
 538  *
 539  * Writes a string value to the #FbMqttMessage.
 540  */
 541 void
 542 fb_mqtt_message_write_str(FbMqttMessage *msg, const gchar *value);
 543
 544 #endif /* PURPLE_FACEBOOK_MQTT_H */