pidgin/pidgin

closing merged branch
port-changes-from-branch-2.x.y-to-default
2020-02-03, Gary Kramlich
2f836435c33c
closing merged branch
/* purple
*
* Purple is the legal property of its developers, whose names are too numerous
* to list here. Please refer to the COPYRIGHT file distributed with this
* source distribution.
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
*/
#ifndef PURPLE_FACEBOOK_MQTT_H
#define PURPLE_FACEBOOK_MQTT_H
/**
* SECTION:mqtt
* @section_id: facebook-mqtt
* @short_description: <filename>mqtt.h</filename>
* @title: MQTT Connection
*
* The MQTT connection.
*/
#include <glib.h>
#include <string.h>
#include "connection.h"
#define FB_TYPE_MQTT fb_mqtt_get_type()
#define FB_TYPE_MQTT_MESSAGE fb_mqtt_message_get_type()
/**
* FB_MQTT_NAME:
*
* The name of the MQTT version.
*/
#define FB_MQTT_NAME "MQTToT"
/**
* FB_MQTT_LEVEL:
*
* 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
/**
* FB_MQTT_HOST:
*
* The MQTT host name for Facebook.
*/
#define FB_MQTT_HOST "mqtt.facebook.com"
/**
* FB_MQTT_PORT:
*
* The MQTT host port for Facebook.
*/
#define FB_MQTT_PORT 443
/**
* 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)
/**
* FB_MQTT_TIMEOUT_PING:
*
* The timeout, in milliseconds, to send a PING to the server.
*/
#define FB_MQTT_TIMEOUT_PING (FB_MQTT_KA * 1000)
/**
* FB_MQTT_ERROR:
*
* The #GQuark of the domain of MQTT errors.
*/
#define FB_MQTT_ERROR fb_mqtt_error_quark()
/**
* 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;
/**
* 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_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;
/**
* 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_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;
/**
* 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_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;
/**
* fb_mqtt_get_type:
*
* Returns: The #GType for an #FbMqtt.
*/
G_DECLARE_FINAL_TYPE(FbMqtt, fb_mqtt, FB, MQTT, GObject)
/**
* fb_mqtt_message_get_type:
*
* Returns: The #GType for an #FbMqttMessage.
*/
G_DECLARE_FINAL_TYPE(FbMqttMessage, fb_mqtt_message, FB, MQTT_MESSAGE,
GObject)
/**
* 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);
/**
* fb_mqtt_new:
* @gc: The #PurpleConnection.
*
* 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(PurpleConnection *gc);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* fb_mqtt_write:
* @mqtt: The #FbMqtt.
* @msg: The #FbMqttMessage.
*
* Writes an #FbMqttMessage to the wire.
*/
void
fb_mqtt_write(FbMqtt *mqtt, FbMqttMessage *msg);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* fb_mqtt_subscribe:
* @mqtt: The #FbMqtt.
* @...: The %NULL-terminated list of topic/QoS pairs.
*
* Sends a message of type #FB_MQTT_MESSAGE_TYPE_SUBSCRIBE.
*/
void fb_mqtt_subscribe(FbMqtt *mqtt, ...) G_GNUC_NULL_TERMINATED;
/**
* 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_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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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);
/**
* 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 /* PURPLE_FACEBOOK_MQTT_H */