changeset
facebook: added GTK-Doc for the internal APIs
Sat, 15 Aug 2015 16:25:23 -0400
- author
- James Geboski <jgeboski@gmail.com>
- date
- Sat, 15 Aug 2015 16:25:23 -0400
- branch
- changeset 37347
- 34d43f8c10d1
- parent 37346
- ce9c78335820
- child 37348
- c639b134dbe6
facebook: added GTK-Doc for the internal APIs
--- a/configure.ac Sat Aug 15 15:17:13 2015 -0400 +++ b/configure.ac Sat Aug 15 16:25:23 2015 -0400 @@ -2730,6 +2730,9 @@ doc/reference/finch/version.xml doc/reference/libpurple/Makefile doc/reference/libpurple/version.xml + doc/reference/protocols/Makefile + doc/reference/protocols/facebook/Makefile + doc/reference/protocols/version.xml doc/reference/pidgin/Makefile doc/reference/pidgin/version.xml m4macros/Makefile
--- a/doc/reference/Makefile.am Sat Aug 15 15:17:13 2015 -0400 +++ b/doc/reference/Makefile.am Sat Aug 15 16:25:23 2015 -0400 @@ -6,4 +6,4 @@ GNT_DIR=finch endif -SUBDIRS = libpurple $(GNT_DIR) $(GTK_DIR) +SUBDIRS = libpurple protocols $(GNT_DIR) $(GTK_DIR)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/reference/protocols/Makefile.am Sat Aug 15 16:25:23 2015 -0400 @@ -0,0 +1,2 @@ +EXTRA_DIST = version.xml.in +SUBDIRS = facebook
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/reference/protocols/facebook/Makefile.am Sat Aug 15 16:25:23 2015 -0400 @@ -0,0 +1,126 @@ +## Process this file with automake to produce Makefile.in + +# We require automake 1.6 at least. +AUTOMAKE_OPTIONS = 1.6 + +# This is a blank Makefile.am for using gtk-doc. +# Copy this to your project's API docs directory and modify the variables to +# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples +# of using the various options. + +# The name of the module, e.g. 'glib'. +DOC_MODULE=facebook + +# Uncomment for versioned docs and specify the version of the module, e.g. '2'. +#DOC_MODULE_VERSION=2 + +# The top-level XML file (SGML in the past). You can change this if you want to. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml + +# The directory containing the source code. Relative to $(srcdir). +# gtk-doc will search all .c & .h files beneath here for inline comments +# documenting the functions and macros. +# e.g. DOC_SOURCE_DIR=../../../gtk +DOC_SOURCE_DIR=$(top_srcdir)/libpurple/protocols/$(DOC_MODULE) + +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +SCANGOBJ_OPTIONS= + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS=\ + --deprecated-guards="PURPLE_DISABLE_DEPRECATED" \ + --rebuild-types \ + --rebuild-sections + +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml +MKDB_OPTIONS=--xml-mode --output-format=xml + +# Extra options to supply to gtkdoc-mktmpl +# e.g. MKTMPL_OPTIONS=--only-section-tmpl +MKTMPL_OPTIONS= + +# Extra options to supply to gtkdoc-mkhtml +MKHTML_OPTIONS= + +# Extra options to supply to gtkdoc-fixref. Not normally needed. +# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html +FIXXREF_OPTIONS= + +# Used for dependencies. The docs will be rebuilt if any of these change. +# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h +# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c +HFILE_GLOB=$(top_srcdir)/libpurple/protocols/$(DOC_MODULE)/*.h +CFILE_GLOB=$(top_srcdir)/libpurple/protocols/$(DOC_MODULE)/*.c + +# Extra header to include when scanning, which are not under DOC_SOURCE_DIR +# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h +# TODO: those files are not properly scanned when building out-of-tree +EXTRA_HFILES = + +# Header files or dirs to ignore when scanning. Use base file/dir names +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code +IGNORE_HFILES=marshal.h + +# Images to copy into HTML directory. +# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png +HTML_IMAGES= + +# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). +# e.g. content_files=running.sgml building.sgml changes-2.0.sgml +content_files = ../version.xml + +# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded +# These files must be listed here *and* in content_files +# e.g. expand_content_files=running.sgml +expand_content_files= + +# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library. +# Only needed if you are using gtkdoc-scangobj to dynamically query widget +# signals and properties. +# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) +GTKDOC_CFLAGS = \ + -I$(top_srcdir) \ + -I$(top_srcdir)/libpurple/protocols/$(DOC_MODULE) \ + $(GLIB_CFLAGS) \ + $(GPLUGIN_CFLAGS) \ + $(DEBUG_CFLAGS) \ + $(JSON_CFLAGS) \ + $(ZLIB_CFLAGS) \ + $(INTROSPECTION_CFLAGS) + +GTKDOC_LIBS = \ + $(top_builddir)/libpurple/protocols/$(DOC_MODULE)/lib$(DOC_MODULE).la \ + $(STATIC_LINK_LIBS) \ + $(GLIB_LIBS) \ + $(GPLUGIN_LIBS) \ + $(INTLLIBS) \ + $(JSON_LIBS) \ + $(ZLIB_LIBS) \ + $(INTROSPECTION_LIBS) + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/gtk-doc.make + +# Other files to distribute +# e.g. EXTRA_DIST += version.xml.in +EXTRA_DIST += version.xml.in + +# Files not to distribute +# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types +# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt +DISTCLEANFILES = $(DOC_MODULE).types $(DOC_MODULE)-sections.txt + +dist-hook: html-build.stamp + +# Comment this out if you want 'make check' to test you doc status +# and run some sanity checks +if ENABLE_GTK_DOC +TESTS_ENVIRONMENT = \ + DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ + SRCDIR=$(abs_srcdir) +#TODO: fix and enable +#TESTS = $(GTKDOC_CHECK) +endif
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/reference/protocols/facebook/facebook-docs.xml Sat Aug 15 16:25:23 2015 -0400 @@ -0,0 +1,32 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ + +<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'"> +<!ENTITY version SYSTEM "../version.xml"> +]> +<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> + <bookinfo> + <title>Purple Reference Manual</title> + <abstract> + <title>Facebook Plugin &version;</title> + <para> + The Facebook Messenger protocol plugin for libpurple. + </para> + </abstract> + </bookinfo> + + <reference label="II"> + <title>API Reference</title> + + <xi:include href="xml/api.xml" /> + <xi:include href="xml/data.xml" /> + <xi:include href="xml/facebook.xml" /> + <xi:include href="xml/http.xml" /> + <xi:include href="xml/id.xml" /> + <xi:include href="xml/json.xml" /> + <xi:include href="xml/mqtt.xml" /> + <xi:include href="xml/thrift.xml" /> + <xi:include href="xml/util.xml" /> + </reference> +</book>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/reference/protocols/version.xml.in Sat Aug 15 16:25:23 2015 -0400 @@ -0,0 +1,1 @@ +@PURPLE_VERSION@
--- a/libpurple/protocols/facebook/api.c Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/api.c Sat Aug 15 16:25:23 2015 -0400 @@ -167,36 +167,76 @@ gklass->dispose = fb_api_dispose; g_type_class_add_private(klass, sizeof (FbApiPrivate)); + /** + * FbApi:cid: + * + * The client identifier for MQTT. This value should be saved + * and loaded for persistence. + */ props[PROP_CID] = g_param_spec_string( "cid", "Client ID", "Client identifier for MQTT", NULL, G_PARAM_READWRITE); + + /** + * FbApi:did: + * + * The device identifier for the MQTT message queue. This value + * should be saved and loaded for persistence. + */ props[PROP_DID] = g_param_spec_string( "did", "Device ID", - "Device identifier", + "Device identifier for the MQTT message queue", NULL, G_PARAM_READWRITE); + + /** + * FbApi:mid: + * + * The MQTT identifier. This value should be saved and loaded + * for persistence. + */ props[PROP_MID] = g_param_spec_uint64( "mid", "MQTT ID", - "MQTT identifier for the MQTT queuer", + "MQTT identifier", 0, G_MAXUINT64, 0, G_PARAM_READWRITE); + + /** + * FbApi:stoken: + * + * The synchronization token for the MQTT message queue. This + * value should be saved and loaded for persistence. + */ props[PROP_STOKEN] = g_param_spec_string( "stoken", "Sync Token", - "Synchronization token for the MQTT queue", + "Synchronization token for the MQTT message queue", NULL, G_PARAM_READWRITE); + + /** + * FbApi:token: + * + * The access token for authentication. This value should be + * saved and loaded for persistence. + */ props[PROP_TOKEN] = g_param_spec_string( "token", "Access Token", - "Access token from authenticating", + "Access token for authentication", NULL, G_PARAM_READWRITE); + + /** + * FbApi:uid: + * + * The #FbId of the user of the #FbApi. + */ props[PROP_UID] = g_param_spec_int64( "uid", "User ID", @@ -205,6 +245,13 @@ G_PARAM_READWRITE); g_object_class_install_properties(gklass, PROP_N, props); + /** + * FbApi::auth: + * @api: The #FbApi. + * + * Emitted upon the successful completion of the authentication + * process. This is emitted as a result of #fb_api_auth(). + */ g_signal_new("auth", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -213,6 +260,14 @@ fb_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * FbApi::connect: + * @api: The #FbApi. + * + * Emitted upon the successful completion of the connection + * process. This is emitted as a result of #fb_api_connect(). + */ g_signal_new("connect", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -221,6 +276,15 @@ fb_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * FbApi::contact: + * @api: The #FbApi. + * @user: The #FbApiUser. + * + * Emitted upon the successful reply of a contact request. This + * is emitted as a result of #fb_api_contact(). + */ g_signal_new("contact", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -229,6 +293,19 @@ fb_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER); + + /** + * FbApi::contacts: + * @api: The #FbApi. + * @users: The #GSList of #FbApiUser's. + * @complete: #TRUE if the list is fetched, otherwise #FALSE. + * + * Emitted upon the successful reply of a contacts request. + * This is emitted as a result of #fb_api_contacts(). This can + * be emitted multiple times before the entire contacts list + * has been fetched. Use @complete for detecting the completion + * status of the list fetch. + */ g_signal_new("contacts", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -237,6 +314,15 @@ fb_marshal_VOID__POINTER_BOOLEAN, G_TYPE_NONE, 2, G_TYPE_POINTER, G_TYPE_BOOLEAN); + + /** + * FbApi::error: + * @api: The #FbApi. + * @error: The #GError. + * + * Emitted whenever an error is hit within the #FbApi. This + * should disconnect #FbApi with #fb_api_disconnect(). + */ g_signal_new("error", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -245,6 +331,14 @@ fb_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_ERROR); + + /** + * FbApi::events: + * @api: The #FbApi. + * @events: The #GSList of #FbApiEvent's. + * + * Emitted upon incoming events from the stream. + */ g_signal_new("events", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -253,6 +347,14 @@ fb_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER); + + /** + * FbApi::messages: + * @api: The #FbApi. + * @msgs: The #GSList of #FbApiMessage's. + * + * Emitted upon incoming messages from the stream. + */ g_signal_new("messages", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -261,6 +363,14 @@ fb_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER); + + /** + * FbApi::presences: + * @api: The #FbApi. + * @press: The #GSList of #FbApiPresence's. + * + * Emitted upon incoming presences from the stream. + */ g_signal_new("presences", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -269,6 +379,15 @@ fb_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER); + + /** + * FbApi::thread: + * @api: The #FbApi. + * @thrd: The #FbApiThread. + * + * Emitted upon the successful reply of a thread request. This + * is emitted as a result of #fb_api_thread(). + */ g_signal_new("thread", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -277,6 +396,16 @@ fb_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER); + + /** + * FbApi::thread-create: + * @api: The #FbApi. + * @tid: The thread #FbId. + * + * Emitted upon the successful reply of a thread creation + * request. This is emitted as a result of + * #fb_api_thread_create(). + */ g_signal_new("thread-create", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -285,6 +414,15 @@ fb_marshal_VOID__INT64, G_TYPE_NONE, 1, FB_TYPE_ID); + + /** + * FbApi::threads: + * @api: The #FbApi. + * @thrds: The #GSList of #FbApiThread's. + * + * Emitted upon the successful reply of a threads request. This + * is emitted as a result of #fb_api_threads(). + */ g_signal_new("threads", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -293,6 +431,14 @@ fb_marshal_VOID__POINTER, G_TYPE_NONE, 1, G_TYPE_POINTER); + + /** + * FbApi::typing: + * @api: The #FbApi. + * @typg: The #FbApiTyping. + * + * Emitted upon an incoming typing state from the stream. + */ g_signal_new("typing", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -1822,7 +1968,7 @@ } void -fb_api_message(FbApi *api, FbId id, gboolean thread, const gchar *msg) +fb_api_message(FbApi *api, FbId id, gboolean thread, const gchar *text) { const gchar *tpfx; FbApiPrivate *priv; @@ -1832,7 +1978,7 @@ JsonBuilder *bldr; g_return_if_fail(FB_IS_API(api)); - g_return_if_fail(msg != NULL); + g_return_if_fail(text != NULL); priv = api->priv; msgid = FB_API_MSGID(g_get_real_time() / 1000, g_random_int()); @@ -1843,7 +1989,7 @@ bldr = fb_json_bldr_new(JSON_NODE_OBJECT); fb_json_bldr_add_int(bldr, "msgid", msgid); - fb_json_bldr_add_str(bldr, "body", msg); + fb_json_bldr_add_str(bldr, "body", text); fb_json_bldr_add_strf(bldr, "sender_fbid", "%" FB_ID_FORMAT, priv->uid); fb_json_bldr_add_strf(bldr, "to", "%s%" FB_ID_FORMAT, tpfx, id); @@ -1853,7 +1999,7 @@ } void -fb_api_publish(FbApi *api, const gchar *topic, const gchar *fmt, ...) +fb_api_publish(FbApi *api, const gchar *topic, const gchar *format, ...) { FbApiPrivate *priv; GByteArray *bytes; @@ -1863,11 +2009,11 @@ g_return_if_fail(FB_IS_API(api)); g_return_if_fail(topic != NULL); - g_return_if_fail(fmt != NULL); + g_return_if_fail(format != NULL); priv = api->priv; - va_start(ap, fmt); - msg = g_strdup_vprintf(fmt, ap); + va_start(ap, format); + msg = g_strdup_vprintf(format, ap); va_end(ap); bytes = g_byte_array_new_take((guint8*) msg, strlen(msg));
--- a/libpurple/protocols/facebook/api.h Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/api.h Sat Aug 15 16:25:23 2015 -0400 @@ -22,6 +22,15 @@ #ifndef _FACEBOOK_API_H_ #define _FACEBOOK_API_H_ +/** + * SECTION:api + * @section_id: facebook-api + * @short_description: <filename>api.h</filename> + * @title: Facebook API + * + * The API for interacting with the Facebook Messenger protocol. + */ + #include "internal.h" #include <glib.h> @@ -32,30 +41,6 @@ #include "id.h" #include "mqtt.h" -#define FB_API_AHOST "https://api.facebook.com" -#define FB_API_BHOST "https://b-api.facebook.com" -#define FB_API_GHOST "https://graph.facebook.com" -#define FB_API_WHOST "https://www.facebook.com" -#define FB_API_KEY "256002347743983" -#define FB_API_SECRET "374e60f8b9bb6b8cbb30f78030438895" - -#define FB_API_CONTACTS_COUNT 500 - -#define FB_API_URL_AUTH FB_API_BHOST "/method/auth.login" -#define FB_API_URL_GQL FB_API_GHOST "/graphql" -#define FB_API_URL_MESSAGES FB_API_WHOST "/messages" -#define FB_API_URL_PARTS FB_API_GHOST "/participants" -#define FB_API_URL_STICKER FB_API_WHOST "/stickers/asset/" -#define FB_API_URL_THREADS FB_API_GHOST "/me/threads" -#define FB_API_URL_TOPIC FB_API_AHOST "/method/messaging.setthreadname" - -#define FB_API_QUERY_CONTACT 10153746900701729 -#define FB_API_QUERY_CONTACTS 10153856456271729 -#define FB_API_QUERY_CONTACTS_AFTER 10153856456281729 -#define FB_API_QUERY_THREAD 10153919752036729 -#define FB_API_QUERY_THREADS 10153919752026729 -#define FB_API_QUERY_XMA 10153919431161729 - #define FB_TYPE_API (fb_api_get_type()) #define FB_API(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), FB_TYPE_API, FbApi)) #define FB_API(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), FB_TYPE_API, FbApi)) @@ -64,23 +49,185 @@ #define FB_IS_API_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), FB_TYPE_API)) #define FB_API_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), FB_TYPE_API, FbApiClass)) -#define FB_API_MSGID(m, i) ((guint64) ( \ +/** + * FB_API_AHOST: + * + * The HTTP host for the Facebook API. + */ +#define FB_API_AHOST "https://api.facebook.com" + +/** + * FB_API_BHOST: + * + * The HTTP host for the Facebook BAPI. + */ +#define FB_API_BHOST "https://b-api.facebook.com" + +/** + * FB_API_GHOST: + * + * The HTTP host for the Facebook Graph API. + */ +#define FB_API_GHOST "https://graph.facebook.com" + +/** + * FB_API_WHOST: + * + * The HTTP host for the Facebook website. + */ +#define FB_API_WHOST "https://www.facebook.com" + +/** + * FB_API_KEY: + * + * The Facebook API key. + */ +#define FB_API_KEY "256002347743983" + +/** + * FB_API_SECRET: + * + * The Facebook API secret. + */ +#define FB_API_SECRET "374e60f8b9bb6b8cbb30f78030438895" + +/** + * FB_API_URL_AUTH: + * + * The URL for authentication requests. + */ +#define FB_API_URL_AUTH FB_API_BHOST "/method/auth.login" + +/** + * FB_API_URL_GQL: + * + * The URL for GraphQL requests. + */ +#define FB_API_URL_GQL FB_API_GHOST "/graphql" + +/** + * FB_API_URL_MESSAGES: + * + * The URL for linking message threads. + */ +#define FB_API_URL_MESSAGES FB_API_WHOST "/messages" + +/** + * FB_API_URL_PARTS: + * + * The URL for participant management requests. + */ +#define FB_API_URL_PARTS FB_API_GHOST "/participants" + +/** + * FB_API_URL_STICKER: + * + * The URL for linking stickers. + */ +#define FB_API_URL_STICKER FB_API_WHOST "/stickers/asset/" + +/** + * FB_API_URL_THREADS: + * + * The URL for thread management requests. + */ +#define FB_API_URL_THREADS FB_API_GHOST "/me/threads" + +/** + * FB_API_URL_TOPIC: + * + * The URL for thread topic requests. + */ +#define FB_API_URL_TOPIC FB_API_AHOST "/method/messaging.setthreadname" + +/** + * FB_API_QUERY_CONTACT: + * + * The query hash for the `FetchContactQuery`. + */ +#define FB_API_QUERY_CONTACT 10153746900701729 + +/** + * FB_API_QUERY_CONTACTS: + * + * The query hash for the `FetchContactsFullQuery`. + */ +#define FB_API_QUERY_CONTACTS 10153856456271729 + +/** + * FB_API_QUERY_CONTACTS_AFTER: + * + * The query hash for the `FetchContactsFullWithAfterQuery`. + */ +#define FB_API_QUERY_CONTACTS_AFTER 10153856456281729 + +/** + * FB_API_QUERY_THREAD: + * + * The query hash for the `ThreadQuery`. + */ +#define FB_API_QUERY_THREAD 10153919752036729 + +/** + * FB_API_QUERY_THREADS: + * + * The query hash for the `ThreadListQuery`. + */ +#define FB_API_QUERY_THREADS 10153919752026729 + +/** + * FB_API_QUERY_XMA: + * + * The query hash for the `XMAQuery`. + */ +#define FB_API_QUERY_XMA 10153919431161729 + +/** + * FB_API_CONTACTS_COUNT: + * + * The maximum amount of contacts to fetch in a single request. If this + * value is set too high, HTTP request will fail. This is due to the + * request data being too large. + */ +#define FB_API_CONTACTS_COUNT 500 + +/** + * FB_API_MSGID: + * @m: The time in milliseconds. + * @i: The random integer. + * + * Creates a 64-bit message identifier in the Facebook format. + * + * Returns: The message identifier. + */ +#define FB_API_MSGID(m, i) ((guint64) ( \ (((guint32) i) & 0x3FFFFF) | \ - (((guint64) m) << 22) \ + (((guint64) m) << 22) \ )) -#define FB_API_ERROR_EMIT(a, e, c) \ - G_STMT_START { \ - if (G_UNLIKELY((e) != NULL)) { \ +/** + * FB_API_ERROR_EMIT: + * @a: The #FbApi. + * @e: The #FbApiError. + * @c: The code to execute. + * + * Emits a #GError on behalf of the #FbApi. + */ +#define FB_API_ERROR_EMIT(a, e, c) \ + G_STMT_START { \ + if (G_UNLIKELY((e) != NULL)) { \ fb_api_error_emit(a, e); \ - {c;} \ - } \ + {c;} \ + } \ } G_STMT_END +/** + * FB_API_ERROR: + * + * The #GQuark of the domain of API errors. + */ #define FB_API_ERROR fb_api_error_quark() -typedef enum _FbApiError FbApiError; -typedef enum _FbApiEventType FbApiEventType; typedef struct _FbApi FbApi; typedef struct _FbApiClass FbApiClass; typedef struct _FbApiPrivate FbApiPrivate; @@ -91,30 +238,63 @@ typedef struct _FbApiTyping FbApiTyping; typedef struct _FbApiUser FbApiUser; - -enum _FbApiError +/** + * FbApiError: + * @FB_API_ERROR_GENERAL: General failure. + * @FB_API_ERROR_AUTH: Authentication failure. + * + * The error codes for the #FB_API_ERROR domain. + */ +typedef enum { FB_API_ERROR_GENERAL, FB_API_ERROR_AUTH -}; +} FbApiError; -enum _FbApiEventType +/** + * FbApiEventType: + * @FB_API_EVENT_TYPE_THREAD_USER_ADDED: A thread user was added. + * @FB_API_EVENT_TYPE_THREAD_USER_REMOVED: A thread user was removed. + * + * The FbApiEvent types. + */ +typedef enum { FB_API_EVENT_TYPE_THREAD_USER_ADDED, FB_API_EVENT_TYPE_THREAD_USER_REMOVED -}; +} FbApiEventType; +/** + * FbApi: + * + * Represents a Facebook Messenger connection. + */ struct _FbApi { + /*< private >*/ GObject parent; FbApiPrivate *priv; }; +/** + * FbApiClass: + * + * The base class for all #FbApi's. + */ struct _FbApiClass { + /*< private >*/ GObjectClass parent_class; }; +/** + * FbApiEvent: + * @type: The #FbApiEventType. + * @uid: The user #FbId. + * @tid: The thread #FbId. + * + * Represents a Facebook update event. + */ struct _FbApiEvent { FbApiEventType type; @@ -122,6 +302,15 @@ FbId tid; }; +/** + * FbApiMessage: + * @uid: The user #FbId. + * @tid: The thread #FbId. + * @text: The message text. + * @isself: #TRUE if the user is the #FbApi user, otherwise #FALSE. + * + * Represents a Facebook user message. + */ struct _FbApiMessage { FbId uid; @@ -130,12 +319,27 @@ gboolean isself; }; +/** + * FbApiPresence: + * @uid: The user #FbId. + * @active: #TRUE if the user is active, otherwise #FALSE. + * + * Represents a Facebook presence message. + */ struct _FbApiPresence { FbId uid; gboolean active; }; +/** + * FbApiThread: + * @tid: The thread #FbId. + * @topic: The topic. + * @users: The #GSList of #FbApiUser's. + * + * Represents a Facebook message thread. + */ struct _FbApiThread { FbId tid; @@ -143,12 +347,28 @@ GSList *users; }; +/** + * FbApiTyping: + * @uid: The user #FbId. + * @state: #TRUE if the user is typing, otherwise #FALSE. + * + * Represents a Facebook typing message. + */ struct _FbApiTyping { FbId uid; gboolean state; }; +/** + * FbApiUser: + * @uid: The user #FbId. + * @name: The name of the user. + * @icon: The icon URL. + * @csum: The checksum of @icon. + * + * Represents a Facebook user. + */ struct _FbApiUser { FbId uid; @@ -157,129 +377,430 @@ gchar *csum; }; - +/** + * fb_api_get_type: + * + * Returns: The #GType for an #FbApi. + */ GType fb_api_get_type(void); +/** + * fb_api_error_quark: + * + * Gets the #GQuark of the domain of API errors. + * + * Returns: The #GQuark of the domain. + */ GQuark fb_api_error_quark(void); +/** + * fb_api_new: + * @gc: The #PurpleConnection. + * + * Creates a new #FbApi. The returned #FbApi should be freed with + * #g_object_unref() when no longer needed. + * + * Returns: The new #FbApi. + */ FbApi * fb_api_new(PurpleConnection *gc); +/** + * fb_api_rehash: + * @api: The #FbApi. + * + * Rehashes and updates internal data of the #FbApi. This should be + * called whenever properties are modified. + */ void fb_api_rehash(FbApi *api); +/** + * fb_api_is_invisible: + * @api: The #FbApi. + * + * Determines if the user of the #FbApi is invisible. + * + * Returns: #TRUE if the #FbApi user is invisible, otherwise #FALSE. + */ gboolean fb_api_is_invisible(FbApi *api); +/** + * fb_api_error: + * @api: The #FbApi. + * @error: The #FbApiError. + * @format: The format string literal. + * @...: The arguments for @format. + * + * Emits an #FbApiError. + */ void -fb_api_error(FbApi *api, FbApiError err, const gchar *fmt, ...) +fb_api_error(FbApi *api, FbApiError error, const gchar *format, ...) G_GNUC_PRINTF(3, 4); +/** + * fb_api_error_emit: + * @api: The #FbApi. + * @error: The #GError. + * + * Emits a #GError on an #FbApiError. + */ void fb_api_error_emit(FbApi *api, GError *error); +/** + * fb_api_auth: + * @api: The #FbApi. + * @user: The Facebook user name, email, or phone number. + * @pass: The Facebook password. + * + * Sends an authentication request to Facebook. This will obtain + * session information, which is required for all other requests. + */ void fb_api_auth(FbApi *api, const gchar *user, const gchar *pass); +/** + * fb_api_contact: + * @api: The #FbApi. + * @uid: The user #FbId. + * + * Sends a contact request. This will obtain the general information of + * a single contact. + */ void fb_api_contact(FbApi *api, FbId uid); +/** + * fb_api_contacts: + * @api: The #FbApi. + * + * Sends a contacts request. This will obtain a full list of detailed + * contact information about the friends of the #FbApi user. + */ void fb_api_contacts(FbApi *api); +/** + * fb_api_connect: + * @api: The #FbApi. + * @invisible: #TRUE to make the user invisible, otherwise #FALSE. + * + * Initializes and establishes the underlying MQTT connection. + */ void fb_api_connect(FbApi *api, gboolean invisible); +/** + * fb_api_disconnect: + * @api: The #FbApi. + * + * Closes the underlying MQTT connection. + */ void fb_api_disconnect(FbApi *api); +/** + * fb_api_message: + * @api: The #FbApi. + * @id: The user or thread #FbId. + * @thread: #TRUE if @id is a thread, otherwise #FALSE. + * @text: The message text. + * + * Sends a message as the user of the #FbApi to a user or a thread. + */ void -fb_api_message(FbApi *api, FbId id, gboolean thread, const gchar *msg); +fb_api_message(FbApi *api, FbId id, gboolean thread, const gchar *text); +/** + * fb_api_publish: + * @api: The #FbApi. + * @topic: The topic. + * @format: The format string literal. + * @...: The arguments for @format. + * + * Publishes an MQTT message. + */ void -fb_api_publish(FbApi *api, const gchar *topic, const gchar *fmt, ...) +fb_api_publish(FbApi *api, const gchar *topic, const gchar *format, ...) G_GNUC_PRINTF(3, 4); +/** + * fb_api_read: + * @api: The #FbApi. + * @id: The user or thread #FbId. + * @thread: #TRUE if @id is a thread, otherwise #FALSE. + * + * Marks a message thread as read. + */ void fb_api_read(FbApi *api, FbId id, gboolean thread); +/** + * fb_api_unread: + * @api: The #FbApi. + * + * Sends an unread message request. + */ void fb_api_unread(FbApi *api); +/** + * fb_api_thread: + * @api: The #FbApi. + * @tid: The thread #FbId. + * + * Sends a thread request. This will obtain the general information of + * a single thread. + */ void fb_api_thread(FbApi *api, FbId tid); +/** + * fb_api_thread_create: + * @api: The #FbApi. + * @uids: The #GSList of #FbId's. + * + * Sends a thread creation request. In order to create a thread, there + * must be at least two other users in @uids. + */ void fb_api_thread_create(FbApi *api, GSList *uids); +/** + * fb_api_thread_invite: + * @api: The #FbApi. + * @tid: The thread #FbId. + * @uid: The user #FbId. + * + * Sends a thread user invitation request. + */ void fb_api_thread_invite(FbApi *api, FbId tid, FbId uid); +/** + * fb_api_thread_remove: + * @api: The #FbApi. + * @tid: The thread #FbId. + * @uid: The user #FbId. + * + * Sends a thread user removal request. + */ void fb_api_thread_remove(FbApi *api, FbId tid, FbId uid); +/** + * fb_api_thread_topic: + * @api: The #FbApi. + * @tid: The thread #FbId. + * @topic: The topic. + * + * Sends a thread topic change request. + */ void fb_api_thread_topic(FbApi *api, FbId tid, const gchar *topic); +/** + * fb_api_threads: + * @api: The #FbApi. + * + * Sends a threads request. This will obtain a full list of detailed + * thread information about the threads of the #FbApi user. + */ void fb_api_threads(FbApi *api); +/** + * fb_api_typing: + * @api: The #FbApi. + * @uid: The user #FbId. + * @state: #TRUE if the #FbApi user is typing, otherwise #FALSE. + * + * Sends a typing state message for the user of the #FbApi. + */ void fb_api_typing(FbApi *api, FbId uid, gboolean state); +/** + * fb_api_event_dup: + * @event: The #FbApiEvent. + * + * Duplicates an #FbApiEvent. + * + * Returns: The new #FbApiEvent. + */ FbApiEvent * fb_api_event_dup(FbApiEvent *event); +/** + * fb_api_event_reset: + * @event: The #FbApiEvent. + * + * Resets an #FbApiEvent. + */ void fb_api_event_reset(FbApiEvent *event); +/** + * fb_api_event_free: + * @event: The #FbApiEvent. + * + * Frees all memory used by the #FbApiEvent. + */ void fb_api_event_free(FbApiEvent *event); +/** + * fb_api_message_dup: + * @msg: The #FbApiMessage. + * @deep: #TRUE to duplicate allocated data, otherwise #FALSE. + * + * Duplicates an #FbApiMessage. + * + * Returns: The new #FbApiMessage. + */ FbApiMessage * fb_api_message_dup(FbApiMessage *msg, gboolean deep); +/** + * fb_api_message_reset: + * @msg: The #FbApiMessage. + * @deep: #TRUE to free allocated data, otherwise #FALSE. + * + * Resets an #FbApiMessage. + */ void fb_api_message_reset(FbApiMessage *msg, gboolean deep); +/** + * fb_api_message_free: + * @msg: The #FbApiMessage. + * + * Frees all memory used by the #FbApiMessage. + */ void fb_api_message_free(FbApiMessage *msg); +/** + * fb_api_presence_dup: + * @pres: The #FbApiPresence. + * + * Duplicates an #FbApiPresence. + * + * Returns: The new #FbApiPresence. + */ FbApiPresence * fb_api_presence_dup(FbApiPresence *pres); +/** + * fb_api_presence_reset: + * @pres: The #FbApiPresence. + * + * Resets an #FbApiPresence. + */ void fb_api_presence_reset(FbApiPresence *pres); +/** + * fb_api_presence_free: + * @pres: The #FbApiPresence. + * + * Frees all memory used by the #FbApiPresence. + */ void fb_api_presence_free(FbApiPresence *pres); +/** + * fb_api_thread_dup: + * @thrd: The #FbApiThread. + * @deep: #TRUE to duplicate allocated data, otherwise #FALSE. + * + * Duplicates an #FbApiThread. + * + * Returns: The new #FbApiThread. + */ FbApiThread * fb_api_thread_dup(FbApiThread *thrd, gboolean deep); +/** + * fb_api_thread_reset: + * @thrd: The #FbApiThread. + * @deep: #TRUE to free allocated data, otherwise #FALSE. + * + * Resets an #FbApiThread. + */ void fb_api_thread_reset(FbApiThread *thrd, gboolean deep); +/** + * fb_api_thread_free: + * @thrd: The #FbApiThread. + * + * Frees all memory used by the #FbApiThread. + */ void fb_api_thread_free(FbApiThread *thrd); +/** + * fb_api_typing_dup: + * @typg: The #FbApiTyping. + * + * Duplicates an #FbApiTyping. + * + * Returns: The new #FbApiTyping. + */ FbApiTyping * fb_api_typing_dup(FbApiTyping *typg); +/** + * fb_api_typing_reset: + * @typg: The #FbApiTyping. + * + * Resets an #FbApiTyping. + */ void fb_api_typing_reset(FbApiTyping *typg); +/** + * fb_api_typing_free: + * @typg: The #FbApiTyping. + * + * Frees all memory used by the #FbApiTyping. + */ void fb_api_typing_free(FbApiTyping *typg); +/** + * fb_api_user_dup: + * @user: The #FbApiUser. + * @deep: #TRUE to duplicate allocated data, otherwise #FALSE. + * + * Duplicates an #FbApiUser. + * + * Returns: The new #FbApiUser. + */ FbApiUser * fb_api_user_dup(FbApiUser *user, gboolean deep); +/** + * fb_api_user_reset: + * @user: The #FbApiUser. + * @deep: #TRUE to free allocated data, otherwise #FALSE. + * + * Resets an #FbApiUser. + */ void fb_api_user_reset(FbApiUser *user, gboolean deep); +/** + * fb_api_user_free: + * @user: The #FbApiUser. + * + * Frees all memory used by the #FbApiUser. + */ void fb_api_user_free(FbApiUser *user);
--- a/libpurple/protocols/facebook/data.h Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/data.h Sat Aug 15 16:25:23 2015 -0400 @@ -22,6 +22,15 @@ #ifndef _FACEBOOK_DATA_H_ #define _FACEBOOK_DATA_H_ +/** + * SECTION:data + * @section_id: facebook-data + * @short_description: <filename>data.h</filename> + * @title: Connection Data + * + * The Connection Data. + */ + #include <glib.h> #include "blistnodetypes.h" @@ -32,8 +41,6 @@ #include "http.h" #include "id.h" -#define FB_DATA_ICON_MAX 4 - #define FB_TYPE_DATA (fb_data_get_type()) #define FB_DATA(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), FB_TYPE_DATA, FbData)) #define FB_DATA(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), FB_TYPE_DATA, FbData)) @@ -42,22 +49,50 @@ #define FB_IS_DATA_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), FB_TYPE_DATA)) #define FB_DATA_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), FB_TYPE_DATA, FbDataClass)) +/** + * FB_DATA_ICON_MAX: + * + * The maximum of number of concurrent icon fetches. + */ +#define FB_DATA_ICON_MAX 4 + typedef struct _FbData FbData; typedef struct _FbDataClass FbDataClass; typedef struct _FbDataPrivate FbDataPrivate; typedef struct _FbDataIcon FbDataIcon; +/** + * FbData: + * + * Represents the connection data used by #FacebookProtocol. + */ struct _FbData { + /*< private >*/ GObject parent; FbDataPrivate *priv; }; +/** + * FbDataClass: + * + * The base class for all #FbData's. + */ struct _FbDataClass { + /*< private >*/ GObjectClass parent_class; }; +/** + * FbDataIcon: + * @fata: The #FbData. + * @buddy: The #PurpleBuddy. + * @url: The image URL. + * @func: The #PurpleHttpCallback. + * + * Represents the data used for fetching icons. + */ struct _FbDataIcon { FbData *fata; @@ -66,57 +101,198 @@ PurpleHttpCallback func; }; - +/** + * fb_data_get_type: + * + * Returns: The #GType for an #FbData. + */ GType fb_data_get_type(void); +/** + * fb_data_new: + * @gc: The #PurpleConnection. + * + * Creates a new #FbData. The returned #FbData should be freed with + * #g_object_unref() when no longer needed. + * + * Returns: The new #FbData. + */ FbData * fb_data_new(PurpleConnection *gc); +/** + * fb_data_load: + * @fata: The #FbData. + * + * Loads the internal data from the underlying #PurpleAccount. + * + * Return: TRUE if all of the data was loaded, otherwise FALSE. + */ gboolean fb_data_load(FbData *fata); +/** + * fb_data_save: + * @fata: The #FbData. + * + * Saves the internal data to the underlying #PurpleAccount. + */ void fb_data_save(FbData *fata); +/** + * fb_data_add_timeout: + * @fata: The #FbData. + * @name: The name of the timeout. + * @interval: The time, in milliseconds, between calls to @func. + * @func: The #GSourceFunc. + * @data: The data passed to @func. + * + * Adds a new callback timer. The callback is called repeatedly on the + * basis of @interval, until @func returns #FALSE. The timeout should + * be cleared with #fb_data_clear_timeout() when no longer needed. + */ void fb_data_add_timeout(FbData *fata, const gchar *name, guint interval, GSourceFunc func, gpointer data); +/** + * fb_data_clear_timeout: + * @fata: The #FbData. + * @name: The name of the timeout. + * @remove: #TRUE to remove from the event loop, otherwise #FALSE. + * + * Clears and removes a callback timer. The only time @remove should be + * #FALSE, is when being called from a #GSourceFunc, which is returning + * #FALSE. + */ void fb_data_clear_timeout(FbData *fata, const gchar *name, gboolean remove); +/** + * fb_data_get_api: + * @fata: The #FbData. + * + * Gets the #FbApi from the #FbData. + * + * Return: The #FbApi. + */ FbApi * fb_data_get_api(FbData *fata); +/** + * fb_data_get_connection: + * @fata: The #FbData. + * + * Gets the #PurpleConnection from the #FbData. + * + * Return: The #PurpleConnection. + */ PurpleConnection * fb_data_get_connection(FbData *fata); +/** + * fb_data_get_roomlist: + * @fata: The #FbData. + * + * Gets the #PurpleRoomlist from the #FbData. + * + * Return: The #PurpleRoomlist. + */ PurpleRoomlist * fb_data_get_roomlist(FbData *fata); +/** + * fb_data_get_unread: + * @fata: The #FbData. + * @id: The #FbId. + * + * Gets the unread state of an #FbId. + * + * Return: #TRUE if the #FbId is unread, otherwise #FALSE. + */ gboolean fb_data_get_unread(FbData *fata, FbId id); +/** + * fb_data_set_roomlist: + * @fata: The #FbData. + * @list: The #PurpleRoomlist. + * + * Sets the #PurpleRoomlist to the #FbData. + */ void fb_data_set_roomlist(FbData *fata, PurpleRoomlist *list); +/** + * fb_data_set_unread: + * @fata: The #FbData. + * @id: The #FbId. + * @unread: #TRUE if the #FbId is unread, otherwise FALSE. + * + * Sets the unread state of an #FbId to the #FbData. + */ void fb_data_set_unread(FbData *fata, FbId id, gboolean unread); +/** + * fb_data_add_message: + * @fata: The #FbData. + * @msg: The #FbApiMessage. + * + * Adds an #FbApiMessage to the #FbData. + */ void fb_data_add_message(FbData *fata, FbApiMessage *msg); +/** + * fb_data_take_messages: + * @fata: The #FbData. + * @uid: The user #FbId. + * + * Gets a #GSList of messages by the user #FbId from the #FbData. The + * #FbApiMessage's are removed from the #FbData. The returned #GSList + * and its #FbApiMessage's should be freed with #fb_api_message_free() + * and #g_slist_free_full() when no longer needed. + */ GSList * fb_data_take_messages(FbData *fata, FbId uid); +/** + * fb_data_icon_add: + * @fata: The #FbData. + * @buddy: The @PurpleBuddy. + * @url: The image URL. + * @func: The #PurpleHttpCallback. + * + * Adds a new #FbDataIcon to the #FbData. This is used to fetch user + * icons from HTTP sources. After calling this, #fb_data_icon_queue() + * should be called to queue the fetching process. The returned + * #FbDataIcon should not be freed. + * + * Return: The #FbDataIcon. + */ FbDataIcon * fb_data_icon_add(FbData *fata, PurpleBuddy *buddy, const gchar *url, PurpleHttpCallback func); +/** + * fb_data_icon_destroy: + * @icon: The #FbDataIcon. + * + * Destroys an #FbDataIcon by removing it from the #FbData, and freeing + * all memory used by it. + */ void fb_data_icon_destroy(FbDataIcon *icon); +/** + * fb_data_icon_queue: + * @fata: The #FbData. + * + * Queues the next #FbDataIcon fetches. + */ void fb_data_icon_queue(FbData *fata);
--- a/libpurple/protocols/facebook/facebook.h Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/facebook.h Sat Aug 15 16:25:23 2015 -0400 @@ -22,6 +22,15 @@ #ifndef _FACEBOOK_H_ #define _FACEBOOK_H_ +/** + * SECTION:facebook + * @section_id: facebook-plugin + * @short_description: <filename>facebook.h</filename> + * @title: Facebook Plugin + * + * The Facebook Messenger #PurpleProtocol. + */ + #include <glib.h> #define FACEBOOK_TYPE_PROTOCOL (facebook_protocol_get_type()) @@ -34,19 +43,34 @@ typedef struct _FacebookProtocol FacebookProtocol; typedef struct _FacebookProtocolClass FacebookProtocolClass; +/** + * FacebookProtocol: + * + * Represents the Facebook #PurpleProtocol. + */ struct _FacebookProtocol { + /*< private >*/ PurpleProtocol parent; }; +/** + * FacebookProtocolClass: + * + * The base class for all #FacebookProtocol's. + */ struct _FacebookProtocolClass { + /*< private >*/ PurpleProtocolClass parent_class; }; /** - * Returns the GType for the FacebookProtocol object. + * facebook_protocol_get_type: + * + * Returns: The #GType for a #FacebookProtocol. */ -G_MODULE_EXPORT GType facebook_protocol_get_type(void); +G_MODULE_EXPORT GType +facebook_protocol_get_type(void); #endif /* _FACEBOOK_H_ */
--- a/libpurple/protocols/facebook/http.h Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/http.h Sat Aug 15 16:25:23 2015 -0400 @@ -22,73 +22,253 @@ #ifndef _FACEBOOK_HTTP_H_ #define _FACEBOOK_HTTP_H_ +/** + * SECTION:http + * @section_id: facebook-http + * @short_description: <filename>http.h</filename> + * @title: HTTP Utilities + * + * The HTTP utilities. + */ + #include <glib.h> #include <libpurple/http.h> +/** + * FB_HTTP_ERROR: + * + * The #GQuark of the domain of HTTP errors. + */ #define FB_HTTP_ERROR fb_http_error_quark() +/** + * FbHttpParams: + * + * Represents a set of key/value HTTP parameters. + */ typedef GHashTable FbHttpParams; -typedef enum _FbHttpError FbHttpError; -enum _FbHttpError +/** + * FbHttpError: + * @FB_HTTP_ERROR_SUCCESS: There is no error. + * @FB_HTTP_ERROR_NOMATCH: The name does not match anything. + * + * The error codes for the #FB_HTTP_ERROR domain. + */ +typedef enum { FB_HTTP_ERROR_SUCCESS = 0, FB_HTTP_ERROR_NOMATCH -}; +} FbHttpError; +/** + * fb_http_error_quark: + * + * Gets the #GQuark of the domain of HTTP errors. + * + * Returns: The #GQuark of the domain. + */ GQuark fb_http_error_quark(void); +/** + * fb_http_error_chk: + * @res: The #PurpleHttpResponse. + * @error: The return location for the #GError, or #NULL. + * + * Checks a #PurpleHttpResponse for success. This optionally assigns an + * appropriate #GError upon failure. + * + * Returns: #TRUE if the request was successful, otherwise #FALSE. + */ gboolean fb_http_error_chk(PurpleHttpResponse *res, GError **error); +/** + * fb_http_params_new: + * + * Creates a new #FbHttpParams. The returned #FbHttpParams should be + * freed with #fb_http_params_free() when no longer needed. Optionally, + * instead of freeing, the returned #FbHttpParams can be closed with + * #fb_http_params_close(). + * + * Returns: The new #FbHttpParams. + */ FbHttpParams * fb_http_params_new(void); +/** + * fb_http_params_new_parse: + * @data: The string containing HTTP parameters. + * @isurl: TRUE if @data is a URL, otherwise FALSE. + * + * Creates a new #FbHttpParams. This parses the #FbHttpParams from a + * string, which can be a URL. The returned #FbHttpParams should be + * freed with #fb_http_params_free() when no longer needed. Optionally, + * instead of freeing, the returned #FbHttpParams can be closed with + * #fb_http_params_close(). + * + * Returns: The new #FbHttpParams. + */ FbHttpParams * fb_http_params_new_parse(const gchar *data, gboolean isurl); +/** + * fb_http_params_free: + * @params: The #FbHttpParams. + * + * Frees all memory used by the #FbHttpParams. + */ void fb_http_params_free(FbHttpParams *params); +/** + * fb_http_params_close: + * @params: The #FbHttpParams. + * @url: The URL or #NULL. + * + * Closes the #FbHttpParams by returning a string representing the HTTP + * parameters. If @url is non-#NULL, then the parameters are appended + * to the value of @url. This frees the #FbHttpParams. The returned + * string should be freed with #g_free() when no longer needed. + * + * Returns: The string representation of the HTTP parameters. + */ gchar * fb_http_params_close(FbHttpParams *params, const gchar *url); +/** + * fb_http_params_get_bool: + * @params: The #FbHttpParams. + * @name: The parameter name. + * @error: The return location for the #GError, or #NULL. + * + * Gets a boolean value from the #FbHttpParams. This optionally assigns + * an appropriate #GError upon failure. + * + * Return: The boolean value. + */ gboolean fb_http_params_get_bool(FbHttpParams *params, const gchar *name, GError **error); +/** + * fb_http_params_get_dbl: + * @params: The #FbHttpParams. + * @name: The parameter name. + * @error: The return location for the #GError, or #NULL. + * + * Gets a floating point value from the #FbHttpParams. This optionally + * assigns an appropriate #GError upon failure. + * + * Return: The floating point value. + */ gdouble fb_http_params_get_dbl(FbHttpParams *params, const gchar *name, GError **error); +/** + * fb_http_params_get_int: + * @params: The #FbHttpParams. + * @name: The parameter name. + * @error: The return location for the #GError, or #NULL. + * + * Gets an integer value from the #FbHttpParams. This optionally + * assigns an appropriate #GError upon failure. + * + * Return: The integer value. + */ gint64 fb_http_params_get_int(FbHttpParams *params, const gchar *name, GError **error); +/** + * fb_http_params_get_str: + * @params: The #FbHttpParams. + * @name: The parameter name. + * @error: The return location for the #GError, or #NULL. + * + * Gets a string value from the #FbHttpParams. This optionally assigns + * an appropriate #GError upon failure. + * + * Return: The string value. + */ const gchar * fb_http_params_get_str(FbHttpParams *params, const gchar *name, GError **error); +/** + * fb_http_params_dup_str: + * @params: The #FbHttpParams. + * @name: The parameter name. + * @error: The return location for the #GError, or #NULL. + * + * Gets a duplicated string value from the #FbHttpParams. This + * optionally assigns an appropriate #GError upon failure. The returned + * string should be freed with #g_free() when no longer needed. + * + * Return: The duplicated string value. + */ gchar * fb_http_params_dup_str(FbHttpParams *params, const gchar *name, GError **error); +/** + * fb_http_params_set_bool: + * @params: The #FbHttpParams. + * @name: The parameter name. + * @value: The value. + * + * Sets a boolean value to the #FbHttpParams. + */ void fb_http_params_set_bool(FbHttpParams *params, const gchar *name, gboolean value); +/** + * fb_http_params_set_dbl: + * @params: The #FbHttpParams. + * @name: The parameter name. + * @value: The value. + * + * Sets a floating point value to the #FbHttpParams. + */ void fb_http_params_set_dbl(FbHttpParams *params, const gchar *name, gdouble value); +/** + * fb_http_params_set_int: + * @params: The #FbHttpParams. + * @name: The parameter name. + * @value: The value. + * + * Sets an integer value to the #FbHttpParams. + */ void fb_http_params_set_int(FbHttpParams *params, const gchar *name, gint64 value); +/** + * fb_http_params_set_str: + * @params: The #FbHttpParams. + * @name: The parameter name. + * @value: The value. + * + * Sets a string value to the #FbHttpParams. + */ void fb_http_params_set_str(FbHttpParams *params, const gchar *name, const gchar *value); +/** + * fb_http_params_set_strf: + * @params: The #FbHttpParams. + * @name: The parameter name. + * @format: The format string literal. + * @...: The arguments for @format. + * + * Sets a formatted string value to the #FbHttpParams. + */ void fb_http_params_set_strf(FbHttpParams *params, const gchar *name, const gchar *format, ...)
--- a/libpurple/protocols/facebook/id.h Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/id.h Sat Aug 15 16:25:23 2015 -0400 @@ -22,28 +22,110 @@ #ifndef _FACEBOOK_ID_H_ #define _FACEBOOK_ID_H_ +/** + * SECTION:id + * @section_id: facebook-id + * @short_description: <filename>id.h</filename> + * @title: Facebook Identifier + * + * The Facebook identifier utilities. + */ + #include <glib.h> #include <glib/gprintf.h> #include "util.h" +/** + * FB_ID_FORMAT: + * + * The format specifier for printing and scanning an #FbId. + */ +#define FB_ID_FORMAT G_GINT64_FORMAT + +/** + * FB_ID_MODIFIER: + * + * The length modifier for printing an #FbId. + */ +#define FB_ID_MODIFIER G_GINT64_MODIFIER + +/** + * FB_ID_STRMAX: + * + * The maximum length, including a null-terminating character, of the + * string representation of an #FbId. + */ +#define FB_ID_STRMAX 21 + +/** + * FB_TYPE_ID: + * + * The #GType of an #FbId. + */ +#define FB_TYPE_ID G_TYPE_INT64 + +/** + * FB_ID_CONSTANT: + * @v: The value. + * + * Inserts a literal #FbId into source code. + * + * Return: The literal #FbId value. + */ #define FB_ID_CONSTANT(v) G_GINT64_CONSTANT(v) -#define FB_ID_FORMAT G_GINT64_FORMAT -#define FB_ID_MODIFIER G_GINT64_MODIFIER -#define FB_ID_STRMAX 21 -#define FB_TYPE_ID G_TYPE_INT64 -#define fb_id_hash g_int64_hash -#define fb_id_equal g_int64_equal -#define FB_ID_FROM_STR(s) \ - g_ascii_strtoll(s, NULL, 10) +/** + * FB_ID_FROM_STR: + * @s: The string value. + * + * Converts a string to an #FbId. + * + * Return: The converted #FbId value. + */ +#define FB_ID_FROM_STR(s) g_ascii_strtoll(s, NULL, 10) + +/** + * FB_ID_IS_STR: + * @s: The string value. + * + * Determines if a string is an #FbId. + * + * Return: #TRUE if the string is an #FbId, otherwise #FALSE. + */ +#define FB_ID_IS_STR(s) fb_util_str_is(s, G_ASCII_DIGIT) -#define FB_ID_IS_STR(s) \ - fb_util_str_is(s, G_ASCII_DIGIT) +/** + * FB_ID_TO_STR: + * @i: The #FbId. + * @s: The string buffer. + * + * Converts an #FbId to a string. The buffer should be at least the + * size of #FB_ID_STRMAX. + * + * Return: The converted string value. + */ +#define FB_ID_TO_STR(i, s) g_sprintf(s, "%" FB_ID_FORMAT, (FbId) i) -#define FB_ID_TO_STR(i, s) \ - g_sprintf(s, "%" FB_ID_FORMAT, (FbId) i) +/** + * fb_id_equal: + * + * Compares the values of two #FbId's for equality. See #g_int64_equal. + */ +#define fb_id_equal g_int64_equal +/** + * fb_id_hash: + * + * Converts a pointer to a #FbId hash value. See #g_int64_hash. + */ +#define fb_id_hash g_int64_hash + +/** + * FbId: + * + * Represents a numeric Facebook identifier. + */ typedef gint64 FbId; #endif /* _FACEBOOK_ID_H_ */
--- a/libpurple/protocols/facebook/json.h Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/json.h Sat Aug 15 16:25:23 2015 -0400 @@ -22,17 +22,40 @@ #ifndef _FACEBOOK_JSON_H_ #define _FACEBOOK_JSON_H_ +/** + * SECTION:json + * @section_id: facebook-json + * @short_description: <filename>json.h</filename> + * @title: JSON Utilities + * + * The JSON utilities. + */ + #include <glib.h> #include <json-glib/json-glib.h> +/** + * FB_JSON_ERROR: + * + * The #GQuark of the domain of JSON errors. + */ #define FB_JSON_ERROR fb_json_error_quark() -typedef enum _FbJsonError FbJsonError; -typedef enum _FbJsonType FbJsonType; typedef struct _FbJsonValue FbJsonValue; typedef struct _FbJsonValues FbJsonValues; -enum _FbJsonError +/** + * FbJsonError: + * @FB_JSON_ERROR_SUCCESS: There is no error. + * @FB_JSON_ERROR_AMBIGUOUS: The node has ambiguous matches. + * @FB_JSON_ERROR_GENERAL: General failure. + * @FB_JSON_ERROR_NOMATCH: The node does not match anything. + * @FB_JSON_ERROR_NULL: The node is of type NULL. + * @FB_JSON_ERROR_TYPE: The node has an unexpected type. + * + * The error codes for the #FB_JSON_ERROR domain. + */ +typedef enum { FB_JSON_ERROR_SUCCESS = 0, FB_JSON_ERROR_AMBIGUOUS, @@ -40,17 +63,36 @@ FB_JSON_ERROR_NOMATCH, FB_JSON_ERROR_NULL, FB_JSON_ERROR_TYPE -}; +} FbJsonError; -enum _FbJsonType +/** + * FbJsonType: + * @FB_JSON_TYPE_NULL: An unknown value. + * @FB_JSON_TYPE_BOOL: A boolean (#TRUE or #FALSE). + * @FB_JSON_TYPE_DBL: A floating point number. + * @FB_JSON_TYPE_INT: A signed integer. + * @FB_JSON_TYPE_STR: A string. + * + * The JSON data types. + */ +typedef enum { FB_JSON_TYPE_NULL = 0, FB_JSON_TYPE_BOOL = G_TYPE_BOOLEAN, FB_JSON_TYPE_DBL = G_TYPE_DOUBLE, FB_JSON_TYPE_INT = G_TYPE_INT64, FB_JSON_TYPE_STR = G_TYPE_STRING -}; +} FbJsonType; +/** + * FbJsonValue: + * @expr: The #JsonPath expression. + * @type: The #FbJsonType. + * @required: TRUE if the node is required, otherwise FALSE. + * @value: The #GValue. + * + * Represents a JSON node value. + */ struct _FbJsonValue { const gchar *expr; @@ -59,6 +101,18 @@ GValue value; }; +/** + * FbJsonValues: + * @root: The root #JsonNode. + * @queue: The queue of #FbJsonValue's. + * @next: The next #FbJsonValue. + * @isarray: #TRUE if an array is present, otherwise #FALSE. + * @array: The #JsonArray or #NULL. + * @index: The advancing array index. + * @error: The #GError. + * + * Represents a JSON value handler. + */ struct _FbJsonValues { JsonNode *root; @@ -72,103 +126,403 @@ GError *error; }; +/** + * fb_json_error_quark: + * + * Gets the #GQuark of the domain of JSON errors. + * + * Returns: The #GQuark of the domain. + */ GQuark fb_json_error_quark(void); +/** + * fb_json_bldr_new: + * @type: The starting #JsonNodeType. + * + * Creates a new #JsonBuilder. The starting #JsonNodeType is likely to + * be #JSON_NODE_OBJECT. The returned #JsonBuilder should be freed with + * #g_object_unref() when no longer needed. Optionally, instead of + * freeing, the returned #JsonBuilder can be closed with + * #fb_json_bldr_close(). + * + * Returns: The new #JsonBuilder. + */ JsonBuilder * fb_json_bldr_new(JsonNodeType type); +/** + * fb_json_bldr_close: + * @bldr: The #JsonBuilder. + * @type: The ending #JsonNodeType. + * @size: The return local for the size of the returned string. + * + * Closes the #JsonBuilder by returning a string representing the + * #JsonBuilder. The ending #JsonNodeType is likely to be + * #JSON_NODE_OBJECT. This calls #g_object_unref(). The returned + * string should be freed with #g_free() when no longer needed. + * + * Returns: The string representation of the #JsonBuilder. + */ gchar * fb_json_bldr_close(JsonBuilder *bldr, JsonNodeType type, gsize *size); +/** + * fb_json_bldr_arr_begin: + * @bldr: The #JsonBuilder. + * @name: The member name, or #NULL. + * + * Begins an array member in the #JsonBuilder. + */ void fb_json_bldr_arr_begin(JsonBuilder *bldr, const gchar *name); +/** + * fb_json_bldr_arr_end: + * @bldr: The #JsonBuilder. + * + * Ends an array member in the #JsonBuilder. + */ void fb_json_bldr_arr_end(JsonBuilder *bldr); +/** + * fb_json_bldr_obj_begin: + * @bldr: The #JsonBuilder. + * @name: The member name, or #NULL. + * + * Begins an object member in the #JsonBuilder. + */ void fb_json_bldr_obj_begin(JsonBuilder *bldr, const gchar *name); +/** + * fb_json_bldr_obj_end: + * @bldr: The #JsonBuilder. + * + * Ends an array member in the #JsonBuilder. + */ void fb_json_bldr_obj_end(JsonBuilder *bldr); +/** + * fb_json_bldr_add_bool: + * @bldr: The #JsonBuilder. + * @name: The member name, or #NULL. + * @value: The value. + * + * Adds a boolean memeber to the #JsonBuilder. + */ void fb_json_bldr_add_bool(JsonBuilder *bldr, const gchar *name, gboolean value); +/** + * fb_json_bldr_add_dbl: + * @bldr: The #JsonBuilder. + * @name: The member name, or #NULL. + * @value: The value. + * + * Adds a floating point memeber to the #JsonBuilder. + */ void fb_json_bldr_add_dbl(JsonBuilder *bldr, const gchar *name, gdouble value); +/** + * fb_json_bldr_add_int: + * @bldr: The #JsonBuilder. + * @name: The member name, or #NULL. + * @value: The value. + * + * Adds a integer memeber to the #JsonBuilder. + */ void fb_json_bldr_add_int(JsonBuilder *bldr, const gchar *name, gint64 value); +/** + * fb_json_bldr_add_str: + * @bldr: The #JsonBuilder. + * @name: The member name, or #NULL. + * @value: The value. + * + * Adds a string memeber to the #JsonBuilder. + */ void fb_json_bldr_add_str(JsonBuilder *bldr, const gchar *name, const gchar *value); +/** + * fb_json_bldr_add_strf: + * @bldr: The #JsonBuilder. + * @name: The member name, or #NULL. + * @format: The format string literal. + * @...: The arguments for @format. + * + * Adds a formatted string memeber to the #JsonBuilder. + */ void fb_json_bldr_add_strf(JsonBuilder *bldr, const gchar *name, const gchar *format, ...) G_GNUC_PRINTF(3, 4); +/** + * fb_json_node_new: + * @data: The string JSON. + * @size: The size of @json, or -1 if null-terminated. + * @error: The return location for the #GError, or #NULL. + * + * Creates a new #JsonNode. The returned #JsonBuilder should be freed + * wuth #json_node_free() when no longer needed. + * + * Returns: The new #JsonNode. + */ JsonNode * fb_json_node_new(const gchar *data, gssize size, GError **error); +/** + * fb_json_node_get: + * @root: The root #JsonNode. + * @expr: The #JsonPath expression. + * @error: The return location for the #GError, or #NULL. + * + * Gets a new #JsonNode value from a parent #JsonNode with a #JsonPath + * expression. The returned #JsonNode should be freed with + * #json_node_free() when no longer needed. + * + * Returns: The new #JsonNode. + */ JsonNode * fb_json_node_get(JsonNode *root, const gchar *expr, GError **error); +/** + * fb_json_node_get_nth: + * @root: The root #JsonNode. + * @n: The index number. + * + * Gets a #JsonNode value from a parent #JsonNode by index. The + * returned #JsonNode should not be freed. + * + * Return: The #JsonNode. + */ JsonNode * fb_json_node_get_nth(JsonNode *root, guint n); +/** + * fb_json_node_get_arr: + * @root: The root #JsonNode. + * @expr: The #JsonPath expression. + * @error: The return location for the #GError, or #NULL. + * + * Gets a new #JsonArray value from a parent #JsonNode with a #JsonPath + * expression. The returned #JsonArray should be freed with + * #json_array_unref() when no longer needed. + * + * Returns: The new #JsonArray. + */ JsonArray * fb_json_node_get_arr(JsonNode *root, const gchar *expr, GError **error); +/** + * fb_json_node_get_bool: + * @root: The root #JsonNode. + * @expr: The #JsonPath expression. + * @error: The return location for the #GError, or #NULL. + * + * Gets a boolean value from a parent #JsonNode with a #JsonPath + * expression. + * + * Returns: The boolean value. + */ gboolean fb_json_node_get_bool(JsonNode *root, const gchar *expr, GError **error); +/** + * fb_json_node_get_dbl: + * @root: The root #JsonNode. + * @expr: The #JsonPath expression. + * @error: The return location for the #GError, or #NULL. + * + * Gets a floating point value from a parent #JsonNode with a #JsonPath + * expression. + * + * Returns: The floating point value. + */ gdouble fb_json_node_get_dbl(JsonNode *root, const gchar *expr, GError **error); +/** + * fb_json_node_get_int: + * @root: The root #JsonNode. + * @expr: The #JsonPath expression. + * @error: The return location for the #GError, or #NULL. + * + * Gets an integer value from a parent #JsonNode with a #JsonPath + * expression. + * + * Returns: The integer value. + */ gint64 fb_json_node_get_int(JsonNode *root, const gchar *expr, GError **error); +/** + * fb_json_node_get_str: + * @root: The root #JsonNode. + * @expr: The #JsonPath expression. + * @error: The return location for the #GError, or #NULL. + * + * Gets an string value from a parent #JsonNode with a #JsonPath + * expression. The returned string should be freed with #g_free() + * when no longer needed. + * + * Returns: The string value. + */ gchar * fb_json_node_get_str(JsonNode *root, const gchar *expr, GError **error); +/** + * fb_json_values_new: + * @root: The root #JsonNode. + * + * Creates a new #FbJsonValues. The returned #FbJsonValues should be + * freed with #fb_json_values_free() when no longer needed. + * + * Returns: The new #FbJsonValues. + */ FbJsonValues * fb_json_values_new(JsonNode *root); +/** + * fb_json_values_free: + * @values: The #FbJsonValues. + * + * Frees all memory used by the #FbJsonValues. + */ void fb_json_values_free(FbJsonValues *values); +/** + * fb_json_values_add: + * @values: The #FbJsonValues. + * @type: The #FbJsonType. + * @required: TRUE if the node is required, otherwise FALSE. + * @expr: The #JsonPath expression. + * + * Adds a new #FbJsonValue to the #FbJsonValues. + */ void fb_json_values_add(FbJsonValues *values, FbJsonType type, gboolean required, const gchar *expr); +/** + * fb_json_values_get_root: + * @values: The #FbJsonValues. + * + * Gets the current working root #JsonNode. This is either the current + * array #JsonNode, or the root #JsonNode. The returned #JsonNode + * should not be freed. + */ JsonNode * fb_json_values_get_root(FbJsonValues *values); +/** + * fb_json_values_set_array: + * @values: The #FbJsonValues. + * @required: TRUE if the node is required, otherwise FALSE. + * @expr: The #JsonPath expression. + * + * Sets the #JsonPath for an array to base all #FbJsonValue's off. + */ void fb_json_values_set_array(FbJsonValues *values, gboolean required, const gchar *expr); +/** + * fb_json_values_update: + * @values: The #FbJsonValues. + * @error: The return location for the #GError, or #NULL. + * + * Updates the current working root. This should be called after all of + * the #FbJsonValue's have been added with #fb_json_values_add(). If an + * array was set with #fb_json_values_set_array(), then this should be + * called in a while loop, until #FALSE is returned. + * + * Returns: #TRUE if the values were updated, otherwise #FALSE. + */ gboolean fb_json_values_update(FbJsonValues *values, GError **error); +/** + * fb_json_values_next: + * @values: The #FbJsonValues. + * + * Gets the next #GValue from the #FbJsonValues. Before calling this + * function, #fb_json_values_update() must be called. + * + * Returns: The #GValue. + */ const GValue * fb_json_values_next(FbJsonValues *values); +/** + * fb_json_values_next_bool: + * @values: The #FbJsonValues. + * @defval: The default value. + * + * Gets the next boolean value from the #FbJsonValues. Before calling + * this function, #fb_json_values_update() must be called. + * + * Returns: The boolean value. + */ gboolean fb_json_values_next_bool(FbJsonValues *values, gboolean defval); +/** + * fb_json_values_next_dbl: + * @values: The #FbJsonValues. + * @defval: The default value. + * + * Gets the next floating point value from the #FbJsonValues. Before + * calling this function, #fb_json_values_update() must be called. + * + * Returns: The floating point value. + */ gdouble fb_json_values_next_dbl(FbJsonValues *values, gdouble defval); +/** + * fb_json_values_next_int: + * @values: The #FbJsonValues. + * @defval: The default value. + * + * Gets the next integer value from the #FbJsonValues. Before calling + * this function, #fb_json_values_update() must be called. + * + * Returns: The integer value. + */ gint64 fb_json_values_next_int(FbJsonValues *values, gint64 defval); +/** + * fb_json_values_next_str: + * @values: The #FbJsonValues. + * @defval: The default value. + * + * Gets the next string value from the #FbJsonValues. Before calling + * this function, #fb_json_values_update() must be called. + * + * Returns: The string value. + */ const gchar * fb_json_values_next_str(FbJsonValues *values, const gchar *defval); +/** + * fb_json_values_next_str_dup: + * @values: The #FbJsonValues. + * @defval: The default value. + * + * Gets the next duplicate string value from the #FbJsonValues. Before + * calling this function, #fb_json_values_update() must be called. + * + * Returns: The duplicate string value. + */ gchar * fb_json_values_next_str_dup(FbJsonValues *values, const gchar *defval);
--- a/libpurple/protocols/facebook/mqtt.c Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/mqtt.c Sat Aug 15 16:25:23 2015 -0400 @@ -84,6 +84,13 @@ gklass->dispose = fb_mqtt_dispose; g_type_class_add_private(klass, sizeof (FbMqttPrivate)); + /** + * FbMqtt::connect: + * @mqtt: The #FbMqtt. + * + * Emitted upon the successful completion of the connection + * process. This is emitted as a result of #fb_mqtt_connect(). + */ g_signal_new("connect", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -92,6 +99,15 @@ fb_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * FbMqtt::error: + * @mqtt: The #FbMqtt. + * @error: The #GError. + * + * Emitted whenever an error is hit within the #FbMqtt. The + * connection is automatically closed after this is emitted. + */ g_signal_new("error", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -100,6 +116,15 @@ fb_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_ERROR); + + /** + * FbMqtt::open: + * @mqtt: The #FbMqtt. + * + * Emitted upon the successful opening of the remote socket. + * This is emitted as a result of #fb_mqtt_open(). This should + * call #fb_mqtt_connect(). + */ g_signal_new("open", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -108,6 +133,15 @@ fb_marshal_VOID__VOID, G_TYPE_NONE, 0); + + /** + * FbMqtt::publish: + * @mqtt: The #FbMqtt. + * @topic: The topic. + * @pload: The payload. + * + * Emitted upon an incoming message from the steam. + */ g_signal_new("publish", G_TYPE_FROM_CLASS(klass), G_SIGNAL_ACTION, @@ -882,33 +916,33 @@ } gboolean -fb_mqtt_message_read_byte(FbMqttMessage *msg, guint8 *byte) +fb_mqtt_message_read_byte(FbMqttMessage *msg, guint8 *value) { - return fb_mqtt_message_read(msg, byte, sizeof *byte); + return fb_mqtt_message_read(msg, value, sizeof *value); } gboolean -fb_mqtt_message_read_mid(FbMqttMessage *msg, guint16 *mid) +fb_mqtt_message_read_mid(FbMqttMessage *msg, guint16 *value) { - return fb_mqtt_message_read_u16(msg, mid); + return fb_mqtt_message_read_u16(msg, value); } gboolean -fb_mqtt_message_read_u16(FbMqttMessage *msg, guint16 *u16) +fb_mqtt_message_read_u16(FbMqttMessage *msg, guint16 *value) { - if (!fb_mqtt_message_read(msg, u16, sizeof *u16)) { + if (!fb_mqtt_message_read(msg, value, sizeof *value)) { return FALSE; } - if (u16 != NULL) { - *u16 = g_ntohs(*u16); + if (value != NULL) { + *value = g_ntohs(*value); } return TRUE; } gboolean -fb_mqtt_message_read_str(FbMqttMessage *msg, gchar **str) +fb_mqtt_message_read_str(FbMqttMessage *msg, gchar **value) { guint8 *data; guint16 size; @@ -917,7 +951,7 @@ return FALSE; } - if (str != NULL) { + if (value != NULL) { data = g_new(guint8, size + 1); data[size] = 0; } else { @@ -929,8 +963,8 @@ return FALSE; } - if (str != NULL) { - *str = (gchar*) data; + if (value != NULL) { + *value = (gchar*) data; } return TRUE; @@ -949,33 +983,33 @@ } void -fb_mqtt_message_write_byte(FbMqttMessage *msg, guint8 byte) +fb_mqtt_message_write_byte(FbMqttMessage *msg, guint8 value) { - fb_mqtt_message_write(msg, &byte, sizeof byte); + fb_mqtt_message_write(msg, &value, sizeof value); } void -fb_mqtt_message_write_mid(FbMqttMessage *msg, guint16 *mid) +fb_mqtt_message_write_mid(FbMqttMessage *msg, guint16 *value) { - g_return_if_fail(mid != NULL); - fb_mqtt_message_write_u16(msg, ++(*mid)); + g_return_if_fail(value != NULL); + fb_mqtt_message_write_u16(msg, ++(*value)); } void -fb_mqtt_message_write_u16(FbMqttMessage *msg, guint16 u16) +fb_mqtt_message_write_u16(FbMqttMessage *msg, guint16 value) { - u16 = g_htons(u16); - fb_mqtt_message_write(msg, &u16, sizeof u16); + value = g_htons(value); + fb_mqtt_message_write(msg, &value, sizeof value); } void -fb_mqtt_message_write_str(FbMqttMessage *msg, const gchar *str) +fb_mqtt_message_write_str(FbMqttMessage *msg, const gchar *value) { gint16 size; - g_return_if_fail(str != NULL); + g_return_if_fail(value != NULL); - size = strlen(str); + size = strlen(value); fb_mqtt_message_write_u16(msg, size); - fb_mqtt_message_write(msg, str, size); + fb_mqtt_message_write(msg, value, size); }
--- a/libpurple/protocols/facebook/mqtt.h Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/mqtt.h Sat Aug 15 16:25:23 2015 -0400 @@ -22,20 +22,20 @@ #ifndef _FACEBOOK_MQTT_H_ #define _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_MQTT_NAME "MQTToT" -#define FB_MQTT_LEVEL 3 -#define FB_MQTT_KA 60 -#define FB_MQTT_HOST "mqtt.facebook.com" -#define FB_MQTT_PORT 443 - -#define FB_MQTT_TIMEOUT_CONN (FB_MQTT_KA * 1500) -#define FB_MQTT_TIMEOUT_PING (FB_MQTT_KA * 1000) - #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(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), FB_TYPE_MQTT, FbMqtt)) @@ -52,13 +52,70 @@ #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)) +/** + * 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() + +/** + * FB_MQTT_SSL_ERROR: + * + * The #GQuark of the domain of MQTT SSL errors. + */ #define FB_MQTT_SSL_ERROR fb_mqtt_ssl_error_quark() -typedef enum _FbMqttConnectFlags FbMqttConnectFlags; -typedef enum _FbMqttError FbMqttError; -typedef enum _FbMqttMessageFlags FbMqttMessageFlags; -typedef enum _FbMqttMessageType FbMqttMessageType; typedef struct _FbMqtt FbMqtt; typedef struct _FbMqttClass FbMqttClass; typedef struct _FbMqttPrivate FbMqttPrivate; @@ -66,7 +123,20 @@ typedef struct _FbMqttMessageClass FbMqttMessageClass; typedef struct _FbMqttMessagePrivate FbMqttMessagePrivate; -enum _FbMqttConnectFlags +/** + * 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, @@ -76,9 +146,21 @@ FB_MQTT_CONNECT_FLAG_QOS0 = 0 << 3, FB_MQTT_CONNECT_FLAG_QOS1 = 1 << 3, FB_MQTT_CONNECT_FLAG_QOS2 = 2 << 3 -}; +} FbMqttConnectFlags; -enum _FbMqttError +/** + * 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, @@ -87,18 +169,47 @@ FB_MQTT_ERROR_USERPASS = 4, FB_MQTT_ERROR_UNAUTHORIZED = 5, FB_MQTT_ERROR_GENERAL -}; +} FbMqttError; -enum _FbMqttMessageFlags +/** + * 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; -enum _FbMqttMessageType +/** + * 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, @@ -114,125 +225,404 @@ FB_MQTT_MESSAGE_TYPE_PINGREQ = 12, FB_MQTT_MESSAGE_TYPE_PINGRESP = 13, FB_MQTT_MESSAGE_TYPE_DISCONNECT = 14 -}; +} FbMqttMessageType; +/** + * FbMqtt: + * + * Represents an MQTT connection. + */ struct _FbMqtt { + /*< private >*/ GObject parent; FbMqttPrivate *priv; }; +/** + * FbMqttClass: + * + * The base class for all #FbMqtt's. + */ struct _FbMqttClass { + /*< private >*/ GObjectClass parent_class; }; +/** + * FbMqttMessage: + * + * Represents a reader/writer for an MQTT message. + */ struct _FbMqttMessage { + /*< private >*/ GObject parent; FbMqttMessagePrivate *priv; }; +/** + * FbMqttMessageClass: + * + * The base class for all #FbMqttMessageClass's. + */ struct _FbMqttMessageClass { + /*< private >*/ GObjectClass parent_class; }; - +/** + * fb_mqtt_get_type: + * + * Returns: The #GType for an #FbMqtt. + */ GType fb_mqtt_get_type(void); +/** + * fb_mqtt_message_get_type: + * + * Returns: The #GType for an #FbMqttMessage. + */ GType fb_mqtt_message_get_type(void); +/** + * 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_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); +/** + * 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 *bytes); +fb_mqtt_publish(FbMqtt *mqtt, const gchar *topic, const GByteArray *pload); +/** + * 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_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 *byte); +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 *mid); +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 *u16); +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 **str); +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 byte); - -void -fb_mqtt_message_write_mid(FbMqttMessage *msg, guint16 *mid); +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_u16(FbMqttMessage *msg, guint16 u16); +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_str(FbMqttMessage *msg, const gchar *str); +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 /* _FACEBOOK_MQTT_H_ */
--- a/libpurple/protocols/facebook/thrift.h Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/thrift.h Sat Aug 15 16:25:23 2015 -0400 @@ -22,6 +22,15 @@ #ifndef _FACEBOOK_THRIFT_H_ #define _FACEBOOK_THRIFT_H_ +/** + * SECTION:thrift + * @section_id: facebook-thrift + * @short_description: <filename>thrift.h</filename> + * @title: Thrift Reader/Writer + * + * The Thrift reader/writer. + */ + #include <glib.h> #include <glib-object.h> @@ -33,12 +42,31 @@ #define FB_IS_THRIFT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), FB_TYPE_THRIFT)) #define FB_THRIFT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), FB_TYPE_THRIFT, FbThriftClass)) -typedef enum _FbThriftType FbThriftType; typedef struct _FbThrift FbThrift; typedef struct _FbThriftClass FbThriftClass; typedef struct _FbThriftPrivate FbThriftPrivate; -enum _FbThriftType +/** + * FbThriftType: + * @FB_THRIFT_TYPE_STOP: A stopper for certain types. + * @FB_THRIFT_TYPE_VOID: A void or empty value. + * @FB_THRIFT_TYPE_BOOL: A boolean (#TRUE or #FALSE). + * @FB_THRIFT_TYPE_BYTE: A signed 8-bit integer. + * @FB_THRIFT_TYPE_DOUBLE: A 64-bit floating point number. + * @FB_THRIFT_TYPE_I16: A signed 16-bit integer. + * @FB_THRIFT_TYPE_I32: A signed 32-bit integer. + * @FB_THRIFT_TYPE_I64: A signed 64-bit integer. + * @FB_THRIFT_TYPE_STRING: A UTF-8 encoded string. + * @FB_THRIFT_TYPE_STRUCT: A set of typed fields. + * @FB_THRIFT_TYPE_MAP: A map of unique keys to values. + * @FB_THRIFT_TYPE_SET: A unique set of values. + * @FB_THRIFT_TYPE_LIST: A ordered list of values. + * @FB_THRIFT_TYPE_ENUM: A 32-bit enumerated list. + * @FB_THRIFT_TYPE_UNKNOWN: An unknown type. + * + * The Thrift data types. + */ +typedef enum { FB_THRIFT_TYPE_STOP = 0, FB_THRIFT_TYPE_VOID = 1, @@ -56,143 +84,517 @@ FB_THRIFT_TYPE_ENUM = 16, FB_THRIFT_TYPE_UNKNOWN +} FbThriftType; -}; - +/** + * FbThrift: + * + * Represents a reader/writer for compact Thrift data. + */ struct _FbThrift { + /*< private >*/ GObject parent; FbThriftPrivate *priv; }; +/** + * FbThriftClass: + * + * The base class for all #FbThrift's. + */ struct _FbThriftClass { + /*< private >*/ GObjectClass parent_class; }; - +/** + * fb_thrift_get_type: + * + * Returns: The #GType for an #FbThrift. + */ GType fb_thrift_get_type(void); +/** + * fb_thrift_new: + * @bytes: The #GByteArray to read or write. + * @offset: The offset in bytes of the data in @bytes. + * + * Creates a new #FbThrift. The returned #FbThrift should be freed with + * #g_object_unref() when no longer needed. This will optionally use a + * #GByteArray at an offset, rather than a newly created and internal + * #GByteArray. + * + * Returns: The new #FbThrift. + */ FbThrift * fb_thrift_new(GByteArray *bytes, guint offset); +/** + * fb_thrift_get_bytes: + * @thft: The #FbThrift. + * + * Gets the underlying #GByteArray of an #FbThrift. + * + * Returns: The #GByteArray. + */ const GByteArray * fb_thrift_get_bytes(FbThrift *thft); +/** + * fb_thrift_get_pos: + * @thft: The #FbThrift. + * + * Gets the cursor position of an #FbThrift. + * + * Returns: The cursor position. + */ guint fb_thrift_get_pos(FbThrift *thft); +/** + * fb_thrift_set_pos: + * @thft: The #FbThrift. + * @pos: The position. + * + * Sets the cursor position of an #FbThrift. + * + * Returns: The #GByteArray. + */ void fb_thrift_set_pos(FbThrift *thft, guint pos); +/** + * fb_thrift_reset: + * @thft: The #FbThrift. + * + * Resets the cursor position of an #FbThrift. + * + * Returns: The #GByteArray. + */ void fb_thrift_reset(FbThrift *thft); +/** + * fb_thrift_read: + * @thft: The #FbThrift. + * @data: The data buffer. + * @size: The size of @buffer. + * + * Reads data from the #FbThrift 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_thrift_read(FbThrift *thft, gpointer data, guint size); +/** + * fb_thrift_read_bool: + * @thft: The #FbThrift. + * @value: The return location for the value, or #NULL. + * + * Reads a boolean value from the #FbThrift. If @value is #NULL, this + * will simply advance the cursor position. + * + * Returns: #TRUE if the value was read, otherwise #FALSE. + */ gboolean fb_thrift_read_bool(FbThrift *thft, gboolean *value); +/** + * fb_thrift_read_byte: + * @thft: The #FbThrift. + * @value: The return location for the value, or #NULL. + * + * Reads an 8-bit integer value from the #FbThrift. If @value is #NULL, + * this will simply advance the cursor position. + * + * Returns: #TRUE if the value was read, otherwise #FALSE. + */ gboolean fb_thrift_read_byte(FbThrift *thft, guint8 *value); +/** + * fb_thrift_read_dbl: + * @thft: The #FbThrift. + * @value: The return location for the value, or #NULL. + * + * Reads a 64-bit floating point value from the #FbThrift. If @value + * is #NULL, this will simply advance the cursor position. + * + * Returns: #TRUE if the value was read, otherwise #FALSE. + */ gboolean fb_thrift_read_dbl(FbThrift *thft, gdouble *value); +/** + * fb_thrift_read_i16: + * @thft: The #FbThrift. + * @value: The return location for the value, or #NULL. + * + * Reads a signed 16-bit integer value from the #FbThrift. This will + * convert the integer from the zig-zag format. If @value is #NULL, + * this will simply advance the cursor position. + * + * Returns: #TRUE if the value was read, otherwise #FALSE. + */ gboolean fb_thrift_read_i16(FbThrift *thft, gint16 *value); +/** + * fb_thrift_read_vi16: + * @thft: The #FbThrift. + * @value: The return location for the value, or #NULL. + * + * Reads a 16-bit integer value from the #FbThrift. This reads the raw + * integer value without converting it from the zig-zag format. If + * @value is #NULL, this will simply advance the cursor position. + * + * Returns: #TRUE if the value was read, otherwise #FALSE. + */ gboolean fb_thrift_read_vi16(FbThrift *thft, guint16 *value); +/** + * fb_thrift_read_i32: + * @thft: The #FbThrift. + * @value: The return location for the value, or #NULL. + * + * Reads a signed 32-bit integer value from the #FbThrift. This will + * convert the integer from the zig-zag format. If @value is #NULL, + * this will simply advance the cursor position. + * + * Returns: #TRUE if the value was read, otherwise #FALSE. + */ gboolean fb_thrift_read_i32(FbThrift *thft, gint32 *value); +/** + * fb_thrift_read_vi32: + * @thft: The #FbThrift. + * @value: The return location for the value, or #NULL. + * + * Reads a 32-bit integer value from the #FbThrift. This reads the raw + * integer value without converting it from the zig-zag format. If + * @value is #NULL, this will simply advance the cursor position. + * + * Returns: #TRUE if the value was read, otherwise #FALSE. + */ gboolean fb_thrift_read_vi32(FbThrift *thft, guint32 *value); +/** + * fb_thrift_read_i64: + * @thft: The #FbThrift. + * @value: The return location for the value, or #NULL. + * + * Reads a signed 64-bit integer value from the #FbThrift. This will + * convert the integer from the zig-zag format. If @value is #NULL, + * this will simply advance the cursor position. + * + * Returns: #TRUE if the value was read, otherwise #FALSE. + */ gboolean fb_thrift_read_i64(FbThrift *thft, gint64 *value); +/** + * fb_thrift_read_vi64: + * @thft: The #FbThrift. + * @value: The return location for the value, or #NULL. + * + * Reads a 64-bit integer value from the #FbThrift. This reads the raw + * integer value without converting it from the zig-zag format. If + * @value is #NULL, this will simply advance the cursor position. + * + * Returns: #TRUE if the value was read, otherwise #FALSE. + */ gboolean fb_thrift_read_vi64(FbThrift *thft, guint64 *value); +/** + * fb_thrift_read_str: + * @thft: The #FbThrift. + * @value: The return location for the value, or #NULL. + * + * Reads a string value from the #FbThrift. 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_thrift_read_str(FbThrift *thft, gchar **value); +/** + * fb_thrift_read_field: + * @thft: The #FbThrift. + * @type: The return location for the #FbThriftType. + * @id: The return location for the identifier, or #NULL. + * + * Reads a field header from the #FbThrift. + * + * Returns: #TRUE if the field header was read, otherwise #FALSE. + */ gboolean fb_thrift_read_field(FbThrift *thft, FbThriftType *type, gint16 *id); +/** + * fb_thrift_read_stop: + * @thft: The #FbThrift. + * + * Reads a field stop from the #FbThrift. + * + * Returns: #TRUE if the field stop was read, otherwise #FALSE. + */ gboolean fb_thrift_read_stop(FbThrift *thft); +/** + * fb_thrift_read_isstop: + * @thft: The #FbThrift. + * + * Determines if the next byte of the #FbThrift is a field stop. + * + * Returns: #TRUE if the next byte is a field stop, otherwise #FALSE. + */ gboolean fb_thrift_read_isstop(FbThrift *thft); +/** + * fb_thrift_read_list: + * @thft: The #FbThrift. + * @type: The return location for the #FbThriftType. + * @size: The return location for the size. + * + * Reads a list header from the #FbThrift. + * + * Returns: #TRUE if the list header was read, otherwise #FALSE. + */ gboolean fb_thrift_read_list(FbThrift *thft, FbThriftType *type, guint *size); +/** + * fb_thrift_read_map: + * @thft: The #FbThrift. + * @ktype: The return location for the key #FbThriftType. + * @vtype: The return location for the value #FbThriftType. + * @size: The return location for the size. + * + * Reads a map header from the #FbThrift. + * + * Returns: #TRUE if the map header was read, otherwise #FALSE. + */ gboolean fb_thrift_read_map(FbThrift *thft, FbThriftType *ktype, FbThriftType *vtype, guint *size); +/** + * fb_thrift_read_set: + * @thft: The #FbThrift. + * @type: The return location for the #FbThriftType. + * @size: The return location for the size. + * + * Reads a set header from the #FbThrift. + * + * Returns: #TRUE if the set header was read, otherwise #FALSE. + */ gboolean fb_thrift_read_set(FbThrift *thft, FbThriftType *type, guint *size); +/** + * fb_thrift_write: + * @thft: The #FbThrift. + * @data: The data buffer. + * @size: The size of @buffer. + * + * Writes data to the #FbThrift. + */ void fb_thrift_write(FbThrift *thft, gconstpointer data, guint size); +/** + * fb_thrift_write_bool: + * @thft: The #FbThrift. + * @value: The value. + * + * Writes a boolean value to the #FbThrift. + */ void fb_thrift_write_bool(FbThrift *thft, gboolean value); +/** + * fb_thrift_write_byte: + * @thft: The #FbThrift. + * @value: The value. + * + * Writes an 8-bit integer value to the #FbThrift. + */ void fb_thrift_write_byte(FbThrift *thft, guint8 value); +/** + * fb_thrift_write_dbl: + * @thft: The #FbThrift. + * @value: The value. + * + * Writes a 64-bit floating point value to the #FbThrift. + */ void fb_thrift_write_dbl(FbThrift *thft, gdouble value); +/** + * fb_thrift_write_i16: + * @thft: The #FbThrift. + * @value: The value. + * + * Writes a signed 16-bit integer value to the #FbThrift. This will + * convert the integer to the zig-zag format. + */ void fb_thrift_write_i16(FbThrift *thft, gint16 value); +/** + * fb_thrift_write_vi16: + * @thft: The #FbThrift. + * @value: The value. + * + * Writes a 16-bit integer value to the #FbThrift. This writes the raw + * integer value without converting it to the zig-zag format. + */ void fb_thrift_write_vi16(FbThrift *thft, guint16 value); +/** + * fb_thrift_write_i32: + * @thft: The #FbThrift. + * @value: The value. + * + * Writes a signed 32-bit integer value to the #FbThrift. This will + * convert the integer to the zig-zag format. + */ void fb_thrift_write_i32(FbThrift *thft, gint32 value); +/** + * fb_thrift_write_vi32: + * @thft: The #FbThrift. + * @value: The value. + * + * Writes a 32-bit integer value to the #FbThrift. This writes the raw + * integer value without converting it to the zig-zag format. + */ void fb_thrift_write_vi32(FbThrift *thft, guint32 value); +/** + * fb_thrift_write_i64: + * @thft: The #FbThrift. + * @value: The value. + * + * Writes a signed 64-bit integer value to the #FbThrift. This will + * convert the integer to the zig-zag format. + */ void fb_thrift_write_i64(FbThrift *thft, gint64 value); +/** + * fb_thrift_write_vi64: + * @thft: The #FbThrift. + * @value: The value. + * + * Writes a 64-bit integer value to the #FbThrift. This writes the raw + * integer value without converting it to the zig-zag format. + */ void fb_thrift_write_vi64(FbThrift *thft, guint64 value); +/** + * fb_thrift_write_str: + * @thft: The #FbThrift. + * @value: The value. + * + * Writes a string value to the #FbThrift. + */ void fb_thrift_write_str(FbThrift *thft, const gchar *value); +/** + * fb_thrift_write_field: + * @thft: The #FbThrift. + * @type: The #FbThriftType. + * @id: The identifier. + * + * Writes a field header to the #FbThrift. + */ void fb_thrift_write_field(FbThrift *thft, FbThriftType type, gint16 id); +/** + * fb_thrift_write_stop: + * @thft: The #FbThrift. + * + * Writes a field stop to the #FbThrift. + */ void fb_thrift_write_stop(FbThrift *thft); +/** + * fb_thrift_write_list: + * @thft: The #FbThrift. + * @type: The #FbThriftType. + * @size: The size. + * + * Writes a list header to the #FbThrift. + */ void fb_thrift_write_list(FbThrift *thft, FbThriftType type, guint size); +/** + * fb_thrift_write_map: + * @thft: The #FbThrift. + * @ktype: The key #FbThriftType. + * @vtype: The value #FbThriftType. + * @size: The size. + * + * Writes a map header to the #FbThrift. + */ void fb_thrift_write_map(FbThrift *thft, FbThriftType ktype, FbThriftType vtype, guint size); +/** + * fb_thrift_write_set: + * @thft: The #FbThrift. + * @type: The #FbThriftType. + * @size: The size. + * + * Writes a set header to the #FbThrift. + */ void fb_thrift_write_set(FbThrift *thft, FbThriftType type, guint size); +/** + * fb_thrift_t2ct: + * @type: The #FbThriftType. + * + * Converts a #FbThriftType to a compact type. + * + * Return: The equivalent compact type. + */ guint8 fb_thrift_t2ct(FbThriftType type); +/** + * fb_thrift_ct2t: + * @type: The compact type. + * + * Converts a compact type to an #FbThriftType. + * + * Return: The equivalent #FbThriftType. + */ FbThriftType fb_thrift_ct2t(guint8 type);
--- a/libpurple/protocols/facebook/util.h Sat Aug 15 15:17:13 2015 -0400 +++ b/libpurple/protocols/facebook/util.h Sat Aug 15 16:25:23 2015 -0400 @@ -22,6 +22,15 @@ #ifndef _FACEBOOK_UTIL_H_ #define _FACEBOOK_UTIL_H_ +/** + * SECTION:util + * @section_id: facebook-util + * @short_description: <filename>util.h</filename> + * @title: General Utilities + * + * The general utilities. + */ + #include <glib.h> #include <libpurple/util.h> @@ -32,101 +41,301 @@ #include "connection.h" #include "conversation.h" -#define FB_UTIL_DEBUG_INFO ( \ - PURPLE_DEBUG_INFO | \ +/** + * FB_UTIL_DEBUG_INFO: + * + * Shortcut #PurpleDebugLevel for unsafe and verbose info messages. + */ +#define FB_UTIL_DEBUG_INFO ( \ + PURPLE_DEBUG_INFO | \ FB_UTIL_DEBUG_FLAG_UNSAFE | \ - FB_UTIL_DEBUG_FLAG_VERBOSE \ + FB_UTIL_DEBUG_FLAG_VERBOSE \ ) +/** + * FB_UTIL_ERROR: + * + * The #GQuark of the domain of utility errors. + */ #define FB_UTIL_ERROR fb_util_error_quark() -typedef enum _FbUtilDebugFlags FbUtilDebugFlags; -typedef enum _FbUtilError FbUtilError; - +/** + * FbUtilRequestBuddyFunc: + * @buddies: The list of #PurpleBuddy's. + * @data: The user-defined data. + */ typedef void (*FbUtilRequestBuddyFunc) (GSList *buddies, gpointer data); -enum _FbUtilDebugFlags +/** + * FbUtilDebugFlags: + * @FB_UTIL_DEBUG_FLAG_UNSAFE: The message is unsafe. + * @FB_UTIL_DEBUG_FLAG_VERBOSE: The message is verbose. + * @FB_UTIL_DEBUG_FLAG_ALL: All of the flags. + * + * The debugging message flags. These flags are inserted on top of + * a #PurpleDebugLevel. + */ +typedef enum { FB_UTIL_DEBUG_FLAG_UNSAFE = 1 << 25, FB_UTIL_DEBUG_FLAG_VERBOSE = 1 << 26, FB_UTIL_DEBUG_FLAG_ALL = 3 << 25 -}; +} FbUtilDebugFlags; -enum _FbUtilError +/** + * FbUtilError: + * @FB_UTIL_ERROR_GENERAL: General failure. + * + * The error codes for the #FB_UTIL_ERROR domain. + */ +typedef enum { FB_UTIL_ERROR_GENERAL -}; +} FbUtilError; - +/** + * fb_util_error_quark: + * + * Gets the #GQuark of the domain of utility errors. + * + * Returns: The #GQuark of the domain. + */ GQuark fb_util_error_quark(void); +/** + * fb_util_account_find_buddy: + * @acct: The #PurpleAccount. + * @chat: The #PurpleChatConversation. + * @name: The name of the buddy. + * @error: The return location for the #GError, or #NULL. + * + * Finds a buddy by their name or alias. + * + * Returns: The #PurpleBuddy if found, otherwise #NULL. + */ PurpleBuddy * fb_util_account_find_buddy(PurpleAccount *acct, PurpleChatConversation *chat, const gchar *name, GError **error); +/** + * fb_util_debug: + * @level: The #PurpleDebugLevel. + * @format: The format string literal. + * @...: The arguments for @format. + * + * Logs a debugging message. If the messages is unsafe or verbose, + * apply the appropriate #FbUtilDebugFlags. + */ void fb_util_debug(PurpleDebugLevel level, const gchar *format, ...) G_GNUC_PRINTF(2, 3); +/** + * fb_util_vdebug: + * @level: The #PurpleDebugLevel. + * @format: The format string literal. + * @ap: The #va_list. + * + * Logs a debugging message. If the messages is unsafe or verbose, + * apply the appropriate #FbUtilDebugFlags. + */ void fb_util_vdebug(PurpleDebugLevel level, const gchar *format, va_list ap); +/** + * fb_util_debug_misc: + * @format: The format string literal. + * @...: The arguments for @format. + * + * Logs a debugging message with the level of #PURPLE_DEBUG_MISC. + */ void fb_util_debug_misc(const gchar *format, ...) G_GNUC_PRINTF(1, 2); +/** + * fb_util_debug_info: + * @format: The format string literal. + * @...: The arguments for @format. + * + * Logs a debugging message with the level of #PURPLE_DEBUG_INFO. + */ void fb_util_debug_info(const gchar *format, ...) G_GNUC_PRINTF(1, 2); +/** + * fb_util_debug_warning: + * @format: The format string literal. + * @...: The arguments for @format. + * + * Logs a debugging message with the level of #PURPLE_DEBUG_WARNING. + */ void fb_util_debug_warning(const gchar *format, ...) G_GNUC_PRINTF(1, 2); +/** + * fb_util_debug_error: + * @format: The format string literal. + * @...: The arguments for @format. + * + * Logs a debugging message with the level of #PURPLE_DEBUG_ERROR. + */ void fb_util_debug_error(const gchar *format, ...) G_GNUC_PRINTF(1, 2); +/** + * fb_util_debug_fatal: + * @format: The format string literal. + * @...: The arguments for @format. + * + * Logs a debugging message with the level of #PURPLE_DEBUG_FATAL. + */ void fb_util_debug_fatal(const gchar *format, ...) G_GNUC_PRINTF(1, 2); +/** + * fb_util_debug_hexdump: + * @level: The #PurpleDebugLevel. + * @bytes: The #GByteArray. + * @format: The format string literal. + * @...: The arguments for @format. + * + * Logs a hexdump of a #GByteArray. If the messages is unsafe or + * verbose, apply the appropriate #FbUtilDebugFlags. + */ void fb_util_debug_hexdump(PurpleDebugLevel level, const GByteArray *bytes, const gchar *format, ...) G_GNUC_PRINTF(3, 4); +/** + * fb_util_locale_str: + * + * Gets the locale string (ex: en_US) from the system. The returned + * string should be freed with #g_free() when no longer needed. + * + * Returns: The locale string. + */ gchar * fb_util_locale_str(void); +/** + * fb_util_randstr: + * @size: The size of the string. + * + * Gets a random alphanumeric string. The returned string should be + * freed with #g_free() when no longer needed. + * + * Returns: The random string. + */ gchar * fb_util_randstr(gsize size); +/** + * fb_util_request_buddy: + * @gc: The #PurpleConnection. + * @title: The title of the message or #NULL. + * @primary: The main point of the message or #NULL. + * @secondary: The secondary information or #NULL. + * @select: A #GSList of selected buddies, or #NULL. + * @multi: #TRUE to for multiple buddy selections, otherwise #FALSE. + * @ok_cb: The callback for the `OK` button or #NULL. + * @cancel_cb: The callback for the `Cancel` button or #NULL. + * @data: The user-defined data. + * + * Displays a buddy list selection form. + * + * Returns: The UI-specific handle. + */ gpointer fb_util_request_buddy(PurpleConnection *gc, const gchar *title, const gchar *primary, const gchar *secondary, GSList *select, gboolean multi, GCallback ok_cb, GCallback cancel_cb, gpointer data); +/** + * fb_util_serv_got_im: + * @gc: The #PurpleConnection. + * @who: The message sender or receiver. + * @text: The message text. + * @flags: The #PurpleMessageFlags. + * @timestamp: The message timestamp. + * + * Handles an incoming IM message. This function is special in that it + * handles self messages. This function determines the direction of the + * message from the #PurpleMessageFlags. + */ void fb_util_serv_got_im(PurpleConnection *gc, const gchar *who, const gchar *text, PurpleMessageFlags flags, guint64 timestamp); +/** + * fb_util_serv_got_chat_in: + * @gc: The #PurpleConnection. + * @id: The id of the chat. + * @who: The message sender or receiver. + * @text: The message text. + * @flags: The #PurpleMessageFlags. + * @timestamp: The message timestamp. + * + * Handles an incoming chat message. This function is special in that + * it handles self messages. This function determines the direction of + * the message from the #PurpleMessageFlags. + */ void fb_util_serv_got_chat_in(PurpleConnection *gc, gint id, const gchar *who, const gchar *text, PurpleMessageFlags flags, guint64 timestamp); +/** + * fb_util_str_is: + * @str: The string. + * @type: The #GAsciiType. + * + * Determines if @str abides to the #GAsciiType. + * + * Returns: #TRUE if the string abides to @type, otherwise #FALSE. + */ gboolean fb_util_str_is(const gchar *str, GAsciiType type); +/** + * fb_util_zcompressed: + * @bytes: The #GByteArray. + * + * Determines if the #GByteArray is zlib compressed. + * + * Returns: #TRUE if the #GByteArray is compressed, otherwise #FALSE. + */ gboolean fb_util_zcompressed(const GByteArray *bytes); +/** + * fb_util_zcompress: + * @bytes: The #GByteArray. + * + * Compresses a #GByteArray with zlib. The returned #GByteArray should + * be freed with #g_byte_array_free() when no longer needed. + * + * Returns: The compressed #GByteArray. + */ GByteArray * fb_util_zcompress(const GByteArray *bytes); +/** + * fb_util_zuncompress: + * @bytes: The #GByteArray. + * + * Uncompresses a #GByteArray with zlib. The returned #GByteArray + * should be freed with #g_byte_array_free() when no longer needed. + * + * Returns: The uncompressed #GByteArray, or #NULL on error. + */ GByteArray * fb_util_zuncompress(const GByteArray *bytes);
