diff options
Diffstat (limited to 'facebook/facebook-mqtt.h')
| -rw-r--r-- | facebook/facebook-mqtt.h | 724 |
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_ */ |