Imported changes from purple-facebook

1 files changed, 527 insertions, 197 deletions

diff --git a/facebook/facebook-mqtt.h b/facebook/facebook-mqtt.h
index c5c63e6..9118a6f 100644
--- a/facebook/facebook-mqtt.h
+++ b/facebook/facebook-mqtt.h
@@ -15,276 +15,606 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** @file **/
+#ifndef _FACEBOOK_MQTT_H_
+#define _FACEBOOK_MQTT_H_
 
-#ifndef _FACEBOOK_MQTT_H
-#define _FACEBOOK_MQTT_H
+/**
+ * SECTION:mqtt
+ * @section_id: facebook-mqtt
+ * @short_description: <filename>facebook-mqtt.h</filename>
+ * @title: MQTT Connection
+ *
+ * The MQTT connection.
+ */
 
 #include <glib.h>
+#include <glib-object.h>
 #include <string.h>
 
-#include "facebook-util.h"
+#define FB_TYPE_MQTT  (fb_mqtt_get_type())
+#define FB_MQTT(obj)  (G_TYPE_CHECK_INSTANCE_CAST((obj), FB_TYPE_MQTT, FbMqtt))
+#define FB_MQTT_CLASS(klass)  (G_TYPE_CHECK_CLASS_CAST((klass), FB_TYPE_MQTT, FbMqttClass))
+#define FB_IS_MQTT(obj)  (G_TYPE_CHECK_INSTANCE_TYPE((obj), FB_TYPE_MQTT))
+#define FB_IS_MQTT_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass), FB_TYPE_MQTT))
+#define FB_MQTT_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), FB_TYPE_MQTT, FbMqttClass))
 
-#define FB_MQTT_NAME "MQIsdp"
-#define FB_MQTT_VERS 3
-#define FB_MQTT_KA   60
-#define FB_MQTT_HOST "mqtt.facebook.com"
-#define FB_MQTT_PORT 443
+#define FB_TYPE_MQTT_MESSAGE  (fb_mqtt_message_get_type())
+#define FB_MQTT_MESSAGE(obj)  (G_TYPE_CHECK_INSTANCE_CAST((obj), FB_TYPE_MQTT_MESSAGE, FbMqttMessage))
+#define FB_MQTT_MESSAGE_CLASS(klass)  (G_TYPE_CHECK_CLASS_CAST((klass), FB_TYPE_MQTT_MESSAGE, FbMqttMessageClass))
+#define FB_IS_MQTT_MESSAGE(obj)  (G_TYPE_CHECK_INSTANCE_TYPE((obj), FB_TYPE_MQTT_MESSAGE))
+#define FB_IS_MQTT_MESSAGE_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass), FB_TYPE_MQTT_MESSAGE))
+#define FB_MQTT_MESSAGE_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS((obj), FB_TYPE_MQTT_MESSAGE, FbMqttMessageClass))
 
-#define FB_MQTT_TIMEOUT_CONN (FB_MQTT_KA * 1500)
-#define FB_MQTT_TIMEOUT_PING (FB_MQTT_KA * 1000)
+/**
+ * FB_MQTT_NAME:
+ *
+ * The name of the MQTT version.
+ */
+#define FB_MQTT_NAME  "MQTToT"
 
 /**
- * Executes one of the #fb_mqtt_funcs.
+ * FB_MQTT_LEVEL:
  *
- * @param m   The #fb_mqtt.
- * @param f   The function to execute.
- * @param ... The operational function arguments.
- **/
-#define FB_MQTT_FUNC(m, f, ...)                    \
-    G_STMT_START {                                 \
-        if (G_LIKELY(m->funcs.f != NULL)) {        \
-            m->funcs.f(m, ##__VA_ARGS__, m->data); \
-        }                                          \
-    } G_STMT_END
+ * The level of the MQTT version.
+ */
+#define FB_MQTT_LEVEL 3
 
+/**
+ * FB_MQTT_KA:
+ *
+ * The keep-alive timeout, in seconds, of the MQTT connection.
+ */
+#define FB_MQTT_KA  60
 
-/** The flags of #fb_mqtt CONNECT packets. **/
-typedef enum fb_mqtt_connect_flags fb_mqtt_connect_flags_t;
+/**
+ * FB_MQTT_HOST:
+ *
+ * The MQTT host name for Facebook.
+ */
+#define FB_MQTT_HOST  "mqtt.facebook.com"
 
-/** The #GError codes of #fb_mqtt. **/
-typedef enum fb_mqtt_error fb_mqtt_error_t;
+/**
+ * FB_MQTT_PORT:
+ *
+ * The MQTT host port for Facebook.
+ */
+#define FB_MQTT_PORT  443
 
-/** The flags of #fb_mqtt messages. **/
-typedef enum fb_mqtt_msg_flags fb_mqtt_msg_flags_t;
+/**
+ * FB_MQTT_TIMEOUT_CONN:
+ *
+ * The timeout, in milliseconds, to wait for a PING back from the
+ * server.
+ */
+#define FB_MQTT_TIMEOUT_CONN (FB_MQTT_KA * 1500)
 
-/** The type of #fb_mqtt messages. **/
-typedef enum fb_mqtt_msg_type fb_mqtt_msg_type_t;
+/**
+ * FB_MQTT_TIMEOUT_PING:
+ *
+ * The timeout, in milliseconds, to send a PING to the server.
+ */
+#define FB_MQTT_TIMEOUT_PING (FB_MQTT_KA * 1000)
 
-/** The main structure for #fb_mqtt callback functions. **/
-typedef struct fb_mqtt_funcs fb_mqtt_funcs_t;
+/**
+ * FB_MQTT_ERROR:
+ *
+ * The #GQuark of the domain of MQTT errors.
+ */
+#define FB_MQTT_ERROR  fb_mqtt_error_quark()
 
-/** The structure for interacting with Facebook MQTT. **/
-typedef struct fb_mqtt fb_mqtt_t;
+/**
+ * FB_MQTT_SSL_ERROR:
+ *
+ * The #GQuark of the domain of MQTT SSL errors.
+ */
+#define FB_MQTT_SSL_ERROR  fb_mqtt_ssl_error_quark()
 
-/** The structure of a #fb_mqtt message. **/
-typedef struct fb_mqtt_msg fb_mqtt_msg_t;
+typedef struct _FbMqtt FbMqtt;
+typedef struct _FbMqttClass FbMqttClass;
+typedef struct _FbMqttPrivate FbMqttPrivate;
+typedef struct _FbMqttMessage FbMqttMessage;
+typedef struct _FbMqttMessageClass FbMqttMessageClass;
+typedef struct _FbMqttMessagePrivate FbMqttMessagePrivate;
 
+/**
+ * FbMqttConnectFlags:
+ * @FB_MQTT_CONNECT_FLAG_CLR: Clear the session.
+ * @FB_MQTT_CONNECT_FLAG_WILL: A will message is in the payload.
+ * @FB_MQTT_CONNECT_FLAG_RET: Retain the will message.
+ * @FB_MQTT_CONNECT_FLAG_PASS: A password is in the payload.
+ * @FB_MQTT_CONNECT_FLAG_USER: A user name is in the payload.
+ * @FB_MQTT_CONNECT_FLAG_QOS0: Use no quality of service.
+ * @FB_MQTT_CONNECT_FLAG_QOS1: Use level one quality of service.
+ * @FB_MQTT_CONNECT_FLAG_QOS2: Use level two quality of service.
+ *
+ * The #FbMqttMessage flags for the CONNECT message.
+ */
+typedef enum
+{
+    FB_MQTT_CONNECT_FLAG_CLR = 1 << 1,
+    FB_MQTT_CONNECT_FLAG_WILL = 1 << 2,
+    FB_MQTT_CONNECT_FLAG_RET = 1 << 5,
+    FB_MQTT_CONNECT_FLAG_PASS = 1 << 6,
+    FB_MQTT_CONNECT_FLAG_USER = 1 << 7,
+    FB_MQTT_CONNECT_FLAG_QOS0 = 0 << 3,
+    FB_MQTT_CONNECT_FLAG_QOS1 = 1 << 3,
+    FB_MQTT_CONNECT_FLAG_QOS2 = 2 << 3
+} FbMqttConnectFlags;
 
 /**
- * The flags of #fb_mqtt CONNECT packets.
- **/
-enum fb_mqtt_connect_flags
+ * FbMqttError:
+ * @FB_MQTT_ERROR_SUCCESS: There is no error.
+ * @FB_MQTT_ERROR_PRTVERS: Unacceptable protocol version.
+ * @FB_MQTT_ERROR_IDREJECT: Identifier rejected.
+ * @FB_MQTT_ERROR_SRVGONE: Server unavailable.
+ * @FB_MQTT_ERROR_USERPASS: Bad user name or password.
+ * @FB_MQTT_ERROR_UNAUTHORIZED: Not authorized.
+ * @FB_MQTT_ERROR_GENERAL: General failure.
+ *
+ * The error codes for the #FB_MQTT_ERROR domain.
+ */
+typedef enum
 {
-    FB_MQTT_CONNECT_FLAG_CLR  = 1 << 1, /** Clear session. **/
-    FB_MQTT_CONNECT_FLAG_WILL = 1 << 2, /** Will flag. **/
-    FB_MQTT_CONNECT_FLAG_RET  = 1 << 5, /** Will retain. **/
-    FB_MQTT_CONNECT_FLAG_PASS = 1 << 6, /** Password. **/
-    FB_MQTT_CONNECT_FLAG_USER = 1 << 7, /** Username. **/
-    FB_MQTT_CONNECT_FLAG_QOS0 = 0 << 3, /** Fire and forget. **/
-    FB_MQTT_CONNECT_FLAG_QOS1 = 1 << 3, /** Acknowledge delivery. **/
-    FB_MQTT_CONNECT_FLAG_QOS2 = 2 << 3  /** Assure delivery. **/
-};
+    FB_MQTT_ERROR_SUCCESS = 0,
+    FB_MQTT_ERROR_PRTVERS = 1,
+    FB_MQTT_ERROR_IDREJECT = 2,
+    FB_MQTT_ERROR_SRVGONE = 3,
+    FB_MQTT_ERROR_USERPASS = 4,
+    FB_MQTT_ERROR_UNAUTHORIZED = 5,
+    FB_MQTT_ERROR_GENERAL
+} FbMqttError;
 
 /**
- * The #GError codes of #fb_mqtt.
- **/
-enum fb_mqtt_error
+ * FbMqttMessageFlags:
+ * @FB_MQTT_MESSAGE_FLAG_RET: Retain messages.
+ * @FB_MQTT_MESSAGE_FLAG_DUP: Duplicate delivery of control packet.
+ * @FB_MQTT_MESSAGE_FLAG_QOS0: Use no quality of service.
+ * @FB_MQTT_MESSAGE_FLAG_QOS1: Use level one quality of service.
+ * @FB_MQTT_MESSAGE_FLAG_QOS2: Use level two quality of service.
+ *
+ * The #FbMqttMessage flags.
+ */
+typedef enum
 {
-    FB_MQTT_ERROR_SUCCESS      = 0, /** Success. **/
-    FB_MQTT_ERROR_PRTVERS      = 1, /** Unacceptable protocol version. **/
-    FB_MQTT_ERROR_IDREJECT     = 2, /** Identifier rejected. **/
-    FB_MQTT_ERROR_SRVGONE      = 3, /** Server unavailable. **/
-    FB_MQTT_ERROR_USERPASS     = 4, /** Bad username or password. **/
-    FB_MQTT_ERROR_UNAUTHORIZED = 5, /** Not authorized. **/
-    FB_MQTT_ERROR_GENERAL           /** General. **/
-};
+    FB_MQTT_MESSAGE_FLAG_RET = 1 << 0,
+    FB_MQTT_MESSAGE_FLAG_DUP = 1 << 3,
+    FB_MQTT_MESSAGE_FLAG_QOS0 = 0 << 1,
+    FB_MQTT_MESSAGE_FLAG_QOS1 = 1 << 1,
+    FB_MQTT_MESSAGE_FLAG_QOS2 = 2 << 1
+} FbMqttMessageFlags;
 
 /**
- * The flags of #fb_mqtt messages.
- **/
-enum fb_mqtt_msg_flags
+ * FbMqttMessageType:
+ * @FB_MQTT_MESSAGE_TYPE_CONNECT: Requests a connection.
+ * @FB_MQTT_MESSAGE_TYPE_CONNACK: Connection acknowledgment.
+ * @FB_MQTT_MESSAGE_TYPE_PUBLISH: Requests a message publication.
+ * @FB_MQTT_MESSAGE_TYPE_PUBACK: Publication acknowledgment.
+ * @FB_MQTT_MESSAGE_TYPE_PUBREC: Publication received.
+ * @FB_MQTT_MESSAGE_TYPE_PUBREL: Publication released.
+ * @FB_MQTT_MESSAGE_TYPE_PUBCOMP: Publication complete.
+ * @FB_MQTT_MESSAGE_TYPE_SUBSCRIBE: Requests a subscription.
+ * @FB_MQTT_MESSAGE_TYPE_SUBACK: Subscription acknowledgment.
+ * @FB_MQTT_MESSAGE_TYPE_UNSUBSCRIBE: Requests an unsubscription.
+ * @FB_MQTT_MESSAGE_TYPE_UNSUBACK: Unsubscription acknowledgment.
+ * @FB_MQTT_MESSAGE_TYPE_PINGREQ: Requests a ping response.
+ * @FB_MQTT_MESSAGE_TYPE_PINGRESP: Ping response.
+ * @FB_MQTT_MESSAGE_TYPE_DISCONNECT: Requests a disconnection.
+ *
+ * The #FbMqttMessage types.
+ */
+typedef enum
 {
-    FB_MQTT_MSG_FLAG_RET  = 1 << 0, /** Retain. **/
-    FB_MQTT_MSG_FLAG_DUP  = 1 << 3, /** Duplicate delivery. **/
-    FB_MQTT_MSG_FLAG_QOS0 = 0 << 1, /** Fire and forget. **/
-    FB_MQTT_MSG_FLAG_QOS1 = 1 << 1, /** Acknowledge delivery. **/
-    FB_MQTT_MSG_FLAG_QOS2 = 2 << 1  /** Assure delivery. **/
-};
+    FB_MQTT_MESSAGE_TYPE_CONNECT = 1,
+    FB_MQTT_MESSAGE_TYPE_CONNACK = 2,
+    FB_MQTT_MESSAGE_TYPE_PUBLISH = 3,
+    FB_MQTT_MESSAGE_TYPE_PUBACK = 4,
+    FB_MQTT_MESSAGE_TYPE_PUBREC = 5,
+    FB_MQTT_MESSAGE_TYPE_PUBREL = 6,
+    FB_MQTT_MESSAGE_TYPE_PUBCOMP = 7,
+    FB_MQTT_MESSAGE_TYPE_SUBSCRIBE = 8,
+    FB_MQTT_MESSAGE_TYPE_SUBACK = 9,
+    FB_MQTT_MESSAGE_TYPE_UNSUBSCRIBE = 10,
+    FB_MQTT_MESSAGE_TYPE_UNSUBACK = 11,
+    FB_MQTT_MESSAGE_TYPE_PINGREQ = 12,
+    FB_MQTT_MESSAGE_TYPE_PINGRESP = 13,
+    FB_MQTT_MESSAGE_TYPE_DISCONNECT = 14
+} FbMqttMessageType;
 
 /**
- * The type of #fb_mqtt messages.
- **/
-enum fb_mqtt_msg_type
+ * FbMqtt:
+ *
+ * Represents an MQTT connection.
+ */
+struct _FbMqtt
 {
-    FB_MQTT_MSG_TYPE_CONNECT     = 1,  /** Connect to Server. **/
-    FB_MQTT_MSG_TYPE_CONNACK     = 2,  /** Connect Acknowledgment. **/
-    FB_MQTT_MSG_TYPE_PUBLISH     = 3,  /** Publish Message. **/
-    FB_MQTT_MSG_TYPE_PUBACK      = 4,  /** Publish Acknowledgment. **/
-    FB_MQTT_MSG_TYPE_PUBREC      = 5,  /** Publish Received. **/
-    FB_MQTT_MSG_TYPE_PUBREL      = 6,  /** Publish Release. **/
-    FB_MQTT_MSG_TYPE_PUBCOMP     = 7,  /** Publish Complete. **/
-    FB_MQTT_MSG_TYPE_SUBSCRIBE   = 8,  /** Client Subscribe request. **/
-    FB_MQTT_MSG_TYPE_SUBACK      = 9,  /** Subscribe Acknowledgment. **/
-    FB_MQTT_MSG_TYPE_UNSUBSCRIBE = 10, /** Client Unsubscribe request. **/
-    FB_MQTT_MSG_TYPE_UNSUBACK    = 11, /** Unsubscribe Acknowledgment. **/
-    FB_MQTT_MSG_TYPE_PINGREQ     = 12, /** PING Request. **/
-    FB_MQTT_MSG_TYPE_PINGRESP    = 13, /** PING Response. **/
-    FB_MQTT_MSG_TYPE_DISCONNECT  = 14  /** Client is Disconnecting. **/
+    /*< private >*/
+    GObject parent;
+    FbMqttPrivate *priv;
 };
 
 /**
- * The main structure for #fb_mqtt callback functions.
- **/
-struct fb_mqtt_funcs
+ * FbMqttClass:
+ *
+ * The base class for all #FbMqtt's.
+ */
+struct _FbMqttClass
 {
-    /**
-     * The error function. This is called whenever an error occurs
-     * within the #fb_mqtt.
-     *
-     * @param mqtt The #fb_mqtt.
-     * @param err  The #GError.
-     * @param data The user-defined data or NULL.
-     **/
-    void (*error) (fb_mqtt_t *mqtt, GError *err, gpointer data);
-
-    /**
-     * The open function. This is called when the connection to the
-     * MQTT has been initialized. This is called as a result of
-     * #fb_mqtt_open(). This function should call #fb_mqtt_connect().
-     *
-     * @param mqtt The #fb_mqtt.
-     * @param data The user-defined data or NULL.
-     **/
-    void (*open) (fb_mqtt_t *mqtt, gpointer data);
-
-    /**
-     * The connack function. This is called when a CONNACK packet is
-     * received. This is called as a result of #fb_mqtt_connect().
-     *
-     * @param mqtt The #fb_mqtt.
-     * @param data The user-defined data or NULL.
-     **/
-    void (*connack) (fb_mqtt_t *mqtt, gpointer data);
-
-    /**
-     * The publish function. This is called when a PUBLISH packet is
-     * received.
-     *
-     * @param mqtt  The #fb_mqtt.
-     * @param topic The message topic.
-     * @param pload The message payload.
-     * @param data  The user-defined data or NULL.
-     **/
-    void (*publish) (fb_mqtt_t *mqtt, const gchar *topic,
-                     const GByteArray *pload, gpointer data);
+    /*< private >*/
+    GObjectClass parent_class;
 };
 
 /**
- * The structure for interacting with Facebook MQTT.
- **/
-struct fb_mqtt
+ * FbMqttMessage:
+ *
+ * Represents a reader/writer for an MQTT message.
+ */
+struct _FbMqttMessage
 {
-    gboolean  connected;   /** TRUE if connected, otherwise FALSE. **/
-
-    fb_mqtt_funcs_t funcs; /** The #fb_mqtt_funcs. **/
-    gpointer        data;  /** The user defined data or NULL. **/
-
-    GError   *err;         /** The #GError or NULL. **/
-    gpointer  ssl;         /** The SSL connection or NULL. **/
-    gint      tev;         /** The timer event identifier. **/
-    gint      rev;         /** The read event identifier. **/
-    gint      wev;         /** The write event identifier. **/
-
-    GByteArray *rbuf;      /** The read buffer. **/
-    GByteArray *wbuf;      /** The write buffer. **/
-    gsize       remz;      /** The remaining read size. **/
-
-    guint16 mid;           /** The message identifier. **/
+    /*< private >*/
+    GObject parent;
+    FbMqttMessagePrivate *priv;
 };
 
 /**
- * The structure of a #fb_mqtt message.
- **/
-struct fb_mqtt_msg
+ * FbMqttMessageClass:
+ *
+ * The base class for all #FbMqttMessageClass's.
+ */
+struct _FbMqttMessageClass
 {
-    fb_mqtt_msg_type_t  type;  /** The #fb_mqtt_msg_type. **/
-    fb_mqtt_msg_flags_t flags; /** The #fb_mqtt_msg_flags. **/
-
-    GByteArray *bytes;         /** The #GByteArray of data. **/
-    guint       offset;        /** The offset of the data. **/
-    guint       pos;           /** The cursor position. **/
-
-    gboolean local;            /** TRUE if the data is local. **/
+    /*< private >*/
+    GObjectClass parent_class;
 };
 
+/**
+ * fb_mqtt_get_type:
+ *
+ * Returns: The #GType for an #FbMqtt.
+ */
+GType
+fb_mqtt_get_type(void);
 
-#define FB_MQTT_ERROR fb_mqtt_error_quark()
-
-GQuark fb_mqtt_error_quark(void);
+/**
+ * fb_mqtt_message_get_type:
+ *
+ * Returns: The #GType for an #FbMqttMessage.
+ */
+GType
+fb_mqtt_message_get_type(void);
 
-fb_mqtt_t *fb_mqtt_new(const fb_mqtt_funcs_t *funcs, gpointer data);
+/**
+ * fb_mqtt_error_quark:
+ *
+ * Gets the #GQuark of the domain of MQTT errors.
+ *
+ * Returns: The #GQuark of the domain.
+ */
+GQuark
+fb_mqtt_error_quark(void);
 
-void fb_mqtt_free(fb_mqtt_t *mqtt);
+/**
+ * fb_mqtt_ssl_error_quark:
+ *
+ * Gets the #GQuark of the domain of MQTT SSL errors.
+ *
+ * Returns: The #GQuark of the domain.
+ */
+GQuark
+fb_mqtt_ssl_error_quark(void);
 
-void fb_mqtt_close(fb_mqtt_t *mqtt);
+/**
+ * fb_mqtt_new:
+ *
+ * Creates a new #FbMqtt. The returned #FbMqtt should be freed with
+ * #g_object_unref() when no longer needed.
+ *
+ * Returns: The new #FbMqtt.
+ */
+FbMqtt *
+fb_mqtt_new(void);
 
-void fb_mqtt_error(fb_mqtt_t *mqtt, fb_mqtt_error_t err, const gchar *fmt, ...)
-    G_GNUC_PRINTF(3, 4);
+/**
+ * fb_mqtt_close:
+ * @mqtt: The #FbMqtt.
+ *
+ * Closes the MQTT without sending the `DISCONNECT` message. The #FbMqtt
+ * may be reopened after calling this.
+ */
+void
+fb_mqtt_close(FbMqtt *mqtt);
 
-void fb_mqtt_read(fb_mqtt_t *mqtt, fb_mqtt_msg_t *msg);
+/**
+ * fb_mqtt_error:
+ * @mqtt: The #FbMqtt.
+ * @error: The #FbMqttError.
+ * @format: The format string literal.
+ * @...: The arguments for @format.
+ *
+ * Emits an #FbMqttError and closes the #FbMqtt.
+ */
+void
+fb_mqtt_error(FbMqtt *mqtt, FbMqttError error, const gchar *format, ...)
+              G_GNUC_PRINTF(3, 4);
 
-void fb_mqtt_write(fb_mqtt_t *mqtt, fb_mqtt_msg_t *msg);
+/**
+ * fb_mqtt_read:
+ * @mqtt: The #FbMqtt.
+ * @msg: The #FbMqttMessage.
+ *
+ * Reads an #FbMqttMessage into the #FbMqtt for processing.
+ */
+void
+fb_mqtt_read(FbMqtt *mqtt, FbMqttMessage *msg);
 
-void fb_mqtt_open(fb_mqtt_t *mqtt, const gchar *host, gint port);
+/**
+ * fb_mqtt_write:
+ * @mqtt: The #FbMqtt.
+ * @msg: The #FbMqttMessage.
+ *
+ * Writes an #FbMqttMessage to the wire.
+ */
+void
+fb_mqtt_write(FbMqtt *mqtt, FbMqttMessage *msg);
 
-void fb_mqtt_connect(fb_mqtt_t *mqtt, guint8 flags, const gchar *cid, ...)
-    G_GNUC_NULL_TERMINATED;
+/**
+ * fb_mqtt_open:
+ * @mqtt: The #FbMqtt.
+ * @host: The host name.
+ * @port: The port.
+ *
+ * Opens an SSL connection to the remote server.
+ */
+void
+fb_mqtt_open(FbMqtt *mqtt, const gchar *host, gint port);
 
-gboolean fb_mqtt_connected(fb_mqtt_t *mqtt, gboolean error);
+/**
+ * fb_mqtt_connect:
+ * @mqtt: The #FbMqtt.
+ * @flags: The #FbMqttConnectFlags.
+ * @pload: The payload.
+ *
+ * Sends a message of type #FB_MQTT_MESSAGE_TYPE_CONNECT.
+ */
+void
+fb_mqtt_connect(FbMqtt *mqtt, guint8 flags, const GByteArray *pload);
 
-void fb_mqtt_disconnect(fb_mqtt_t *mqtt);
+/**
+ * fb_mqtt_connected:
+ * @mqtt: The #FbMqtt.
+ * @error: #TRUE to error with no connection, otherwise #FALSE.
+ *
+ * Determines the connection state of the #FbMqtt, and optionally emits
+ * an error.
+ *
+ * Returns: #TRUE if the #FbMqtt is connected, otherwise #FALSE.
+ */
+gboolean
+fb_mqtt_connected(FbMqtt *mqtt, gboolean error);
 
-void fb_mqtt_publish(fb_mqtt_t *mqtt, const gchar *topic,
-                     const GByteArray *bytes);
+/**
+ * fb_mqtt_disconnect:
+ * @mqtt: The #FbMqtt.
+ *
+ * Sends a message of type #FB_MQTT_MESSAGE_TYPE_DISCONNECT, and closes
+ * the connection.
+ */
+void
+fb_mqtt_disconnect(FbMqtt *mqtt);
 
-void fb_mqtt_subscribe(fb_mqtt_t *mqtt, const gchar *topic1, guint16 qos1, ...)
-    G_GNUC_NULL_TERMINATED;
+/**
+ * fb_mqtt_publish:
+ * @mqtt: The #FbMqtt.
+ * @topic: The topic.
+ * @pload: The payload.
+ *
+ * Sends a message of type #FB_MQTT_MESSAGE_TYPE_PUBLISH.
+ */
+void
+fb_mqtt_publish(FbMqtt *mqtt, const gchar *topic, const GByteArray *pload);
 
-void fb_mqtt_unsubscribe(fb_mqtt_t *mqtt, const gchar *topic1, ...)
-    G_GNUC_NULL_TERMINATED;
+/**
+ * fb_mqtt_subscribe:
+ * @mqtt: The #FbMqtt.
+ * @topic1: The first topic.
+ * @qos1: The first QoS.
+ * @...: The %NULL-terminated list of topic/QoS pairs.
+ *
+ * Sends a message of type #FB_MQTT_MESSAGE_TYPE_SUBSCRIBE.
+ */
+void
+fb_mqtt_subscribe(FbMqtt *mqtt, const gchar *topic1, guint16 qos1, ...)
+                  G_GNUC_NULL_TERMINATED;
 
-fb_mqtt_msg_t *fb_mqtt_msg_new(fb_mqtt_msg_type_t type,
-                               fb_mqtt_msg_flags_t flags);
+/**
+ * fb_mqtt_unsubscribe:
+ * @mqtt: The #FbMqtt.
+ * @topic1: The first topic.
+ * @...: The %NULL-terminated list of topics.
+ *
+ * Sends a message of type #FB_MQTT_MESSAGE_TYPE_UNSUBSCRIBE.
+ */
+void
+fb_mqtt_unsubscribe(FbMqtt *mqtt, const gchar *topic1, ...)
+                    G_GNUC_NULL_TERMINATED;
 
-fb_mqtt_msg_t *fb_mqtt_msg_new_bytes(GByteArray *bytes);
+/**
+ * fb_mqtt_message_new:
+ * @type: The #FbMqttMessageType.
+ * @flags: The #FbMqttMessageFlags.
+ *
+ * Creates a new #FbMqttMessage. The returned #FbMqttMessage should be
+ * freed with #g_object_unref() when no longer needed.
+ *
+ * Returns: The new #FbMqttMessage.
+ */
+FbMqttMessage *
+fb_mqtt_message_new(FbMqttMessageType type, FbMqttMessageFlags flags);
 
-void fb_mqtt_msg_free(fb_mqtt_msg_t *msg);
+/**
+ * fb_mqtt_message_new_bytes:
+ * @bytes: The #GByteArray.
+ *
+ * Creates a new #FbMqttMessage from a #GByteArray. The returned
+ * #FbMqttMessage should be freed with #g_object_unref() when no
+ * longer needed.
+ *
+ * Returns: The new #FbMqttMessage.
+ */
+FbMqttMessage *
+fb_mqtt_message_new_bytes(GByteArray *bytes);
 
-void fb_mqtt_msg_reset(fb_mqtt_msg_t *msg);
+/**
+ * fb_mqtt_message_reset:
+ * @msg: The #FbMqttMessage.
+ *
+ * Resets an #FbMqttMessage. This resets the cursor position, and
+ * removes any sort of fixed header.
+ */
+void
+fb_mqtt_message_reset(FbMqttMessage *msg);
 
-const GByteArray *fb_mqtt_msg_bytes(fb_mqtt_msg_t *msg);
+/**
+ * fb_mqtt_message_bytes:
+ * @msg: The #FbMqttMessage.
+ *
+ * Formats the internal #GByteArray of the #FbMqttMessage with the
+ * required fixed header. This resets the cursor position.
+ *
+ * Returns: The internal #GByteArray.
+ */
+const GByteArray *
+fb_mqtt_message_bytes(FbMqttMessage *msg);
 
-gboolean fb_mqtt_msg_read(fb_mqtt_msg_t *msg, gpointer data, guint size);
+/**
+ * fb_mqtt_message_read:
+ * @msg: The #FbMqttMessage.
+ * @data: The data buffer.
+ * @size: The size of @buffer.
+ *
+ * Reads data from the #FbMqttMessage into a buffer. If @data is #NULL,
+ * this will simply advance the cursor position.
+ *
+ * Returns: #TRUE if the data was read, otherwise #FALSE.
+ */
+gboolean
+fb_mqtt_message_read(FbMqttMessage *msg, gpointer data, guint size);
 
-gboolean fb_mqtt_msg_read_r(fb_mqtt_msg_t *msg, GByteArray *bytes);
+/**
+ * fb_mqtt_message_read_r:
+ * @msg: The #FbMqttMessage.
+ * @bytes: The #GByteArray.
+ *
+ * Reads the remaining data from the #FbMqttMessage into a #GByteArray.
+ * This is useful for obtaining the payload of a message.
+ *
+ * Returns: #TRUE if the data was read, otherwise #FALSE.
+ */
+gboolean
+fb_mqtt_message_read_r(FbMqttMessage *msg, GByteArray *bytes);
 
-gboolean fb_mqtt_msg_read_byte(fb_mqtt_msg_t *msg, guint8 *byte);
+/**
+ * fb_mqtt_message_read_byte:
+ * @msg: The #FbMqttMessage.
+ * @value: The return location for the value, or #NULL.
+ *
+ * Reads an 8-bit integer value from the #FbMqttMessage. If @value is
+ * #NULL, this will simply advance the cursor position.
+ *
+ * Returns: #TRUE if the value was read, otherwise #FALSE.
+ */
+gboolean
+fb_mqtt_message_read_byte(FbMqttMessage *msg, guint8 *value);
 
-gboolean fb_mqtt_msg_read_mid(fb_mqtt_msg_t *msg, guint16 *mid);
+/**
+ * fb_mqtt_message_read_mid:
+ * @msg: The #FbMqttMessage.
+ * @value: The return location for the value, or #NULL.
+ *
+ * Reads a message identifier from the #FbMqttMessage. If @value is
+ * #NULL, this will simply advance the cursor position.
+ *
+ * Returns: #TRUE if the value was read, otherwise #FALSE.
+ */
+gboolean
+fb_mqtt_message_read_mid(FbMqttMessage *msg, guint16 *value);
 
-gboolean fb_mqtt_msg_read_u16(fb_mqtt_msg_t *msg, guint16 *u16);
+/**
+ * fb_mqtt_message_read_u16:
+ * @msg: The #FbMqttMessage.
+ * @value: The return location for the value, or #NULL.
+ *
+ * Reads a 16-bit integer value from the #FbMqttMessage. If @value is
+ * #NULL, this will simply advance the cursor position.
+ *
+ * Returns: #TRUE if the value was read, otherwise #FALSE.
+ */
+gboolean
+fb_mqtt_message_read_u16(FbMqttMessage *msg, guint16 *value);
 
-gboolean fb_mqtt_msg_read_str(fb_mqtt_msg_t *msg, gchar **str);
+/**
+ * fb_mqtt_message_read_str:
+ * @msg: The #FbMqttMessage.
+ * @value: The return location for the value, or #NULL.
+ *
+ * Reads a string value from the #FbMqttMessage. The value returned to
+ * @value should be freed with #g_free() when no longer needed. If
+ * @value is #NULL, this will simply advance the cursor position.
+ *
+ * Returns: #TRUE if the value was read, otherwise #FALSE.
+ */
+gboolean
+fb_mqtt_message_read_str(FbMqttMessage *msg, gchar **value);
 
-void fb_mqtt_msg_write(fb_mqtt_msg_t *msg, gconstpointer data, guint size);
+/**
+ * fb_mqtt_message_write:
+ * @msg: The #FbMqttMessage.
+ * @data: The data buffer.
+ * @size: The size of @buffer.
+ *
+ * Writes data to the #FbMqttMessage.
+ */
+void
+fb_mqtt_message_write(FbMqttMessage *msg, gconstpointer data, guint size);
 
-void fb_mqtt_msg_write_byte(fb_mqtt_msg_t *msg, guint8 byte);
+/**
+ * fb_mqtt_message_write_byte:
+ * @msg: The #FbMqttMessage.
+ * @value: The value.
+ *
+ * Writes an 8-bit integer value to the #FbMqttMessage.
+ */
+void
+fb_mqtt_message_write_byte(FbMqttMessage *msg, guint8 value);
 
-void fb_mqtt_msg_write_mid(fb_mqtt_msg_t *msg, guint16 *mid);
+/**
+ * fb_mqtt_message_write_mid:
+ * @msg: The #FbMqttMessage.
+ * @value: The value.
+ *
+ * Writes a message identifier to the #FbMqttMessage. This increments
+ * @value for the next message.
+ */
+void
+fb_mqtt_message_write_mid(FbMqttMessage *msg, guint16 *value);
 
-void fb_mqtt_msg_write_u16(fb_mqtt_msg_t *msg, guint16 u16);
+/**
+ * fb_mqtt_message_write_u16:
+ * @msg: The #FbMqttMessage.
+ * @value: The value.
+ *
+ * Writes a 16-bit integer value to the #FbMqttMessage.
+ */
+void
+fb_mqtt_message_write_u16(FbMqttMessage *msg, guint16 value);
 
-void fb_mqtt_msg_write_str(fb_mqtt_msg_t *msg, const gchar *str);
+/**
+ * fb_mqtt_message_write_str:
+ * @msg: The #FbMqttMessage.
+ * @value: The value.
+ *
+ * Writes a string value to the #FbMqttMessage.
+ */
+void
+fb_mqtt_message_write_str(FbMqttMessage *msg, const gchar *value);
 
-#endif /* _FACEBOOK_MQTT_H */
+#endif /* _FACEBOOK_MQTT_H_ */