Rework MatrixClient as an interface

docs/reference/matrix-glib/matrix-glib-sections.txt

@@ -1,17 +1,21 @@
 <SECTION>
 <FILE>matrix-client</FILE>
 <TITLE>MatrixClient</TITLE>
-matrix_client_new
-<SUBSECTION Standard>
 MatrixClient
-MatrixClientClass
+MatrixClientInterface
-MATRIX_IS_CLIENT
+matrix_client_register_with_password
-MATRIX_IS_CLIENT_CLASS
+matrix_client_login_with_password
+matrix_client_logout
+matrix_client_refresh_token
+matrix_client_begin_polling
+matrix_client_stop_polling
+matrix_client_get_room
+matrix_client_get_user
+<SUBSECTION Standard>
+MATRIX_CLIENT_GET_IFACE
 MATRIX_CLIENT
-MATRIX_CLIENT_CLASS
+MATRIX_IS_CLIENT
-MATRIX_CLIENT_GET_CLASS
 MATRIX_TYPE_CLIENT
-MatrixClientPrivate
 matrix_client_get_type
 </SECTION>
 

src/matrix-client.c

@@ -17,161 +17,149 @@
  */
 
 #include "matrix-client.h"
-#include "matrix-api.h"
+#include "matrix-marshalers.h"
 
 /**
  * SECTION:matrix-client
- * @short_description: Base class for communication with a Matrix.org server
+ * @short_description: Base interface for communication with a Matrix.org server
  * @title: MatrixClient
  * @stability: Unstable
- * @include: matrix-glib/matrix.h
+ * @include: matrix-glib/matrix-client.h
  *
- * This is the base class for client communication with a Matrix.org server.
+ * This is the base interface for client communication with a
+ * Matrix.org server.
+ */
+
+/**
+ * MatrixClientInterface:
+ * @login_with_password: virtual function for
+ *                       matrix_client_login_with_password()
+ * @register_with_password: virtual function for
+ *                          matrix_client_register_with_password()
+ * @logout: virtual function for matrix_client_logout()
+ * @refresh_token: virtual function for matrix_client_refresh_token()
+ * @begin_polling: virtual function for matrix_client_begin_polling()
+ * @stop_polling: virtual function for matrix_client_stop_polling()
+ * @get_room: virtual function for matrix_client_get_room()
+ * @get_user: virtual function for matrix_client_get_user()
+ *
+ * The interface vtable for #MatrixClient
  */
 
 /**
  * MatrixClient:
  *
- * The MatrixClient object’s instance definition.
+ * The MatrixClient object’s interface definition.
  */
 
-/**
+G_DEFINE_INTERFACE(MatrixClient, matrix_client, G_TYPE_OBJECT);
- * MatrixClientClass:
- * @parent_class: the parent class structure (#GObjectClass)
- *
- * The MatrixClient object’s class definition.
- */
-
-typedef struct _MatrixClientPrivate {
-    MatrixAPI *api;
-} MatrixClientPrivate;
-
-G_DEFINE_TYPE_WITH_PRIVATE(MatrixClient, matrix_client, G_TYPE_OBJECT);
-
-enum {
-    PROP_HOMESERVER = 1,
-    PROP_TOKEN,
-    N_PROPERTIES
-};
-
-static GParamSpec *obj_properties[N_PROPERTIES] = {NULL,};
 
 static void
-matrix_client_finalize(GObject *gobject)
+matrix_client_default_init(MatrixClientInterface *iface)
 {
-    g_signal_handlers_destroy(gobject);
-    G_OBJECT_CLASS(matrix_client_parent_class)->finalize(gobject);
-}
-
-static void
-matrix_client_dispose(GObject *gobject)
-{
-    MatrixClientPrivate *priv = matrix_client_get_instance_private(
-            MATRIX_CLIENT(gobject));
-
-    g_clear_object(&priv->api);
-
-    G_OBJECT_CLASS(matrix_client_parent_class)->dispose(gobject);
-}
-
-static void
-matrix_client_set_property(GObject *gobject,
-                           guint prop_id,
-                           const GValue *value,
-                           GParamSpec *pspec)
-{
-    switch (prop_id) {
-        case PROP_HOMESERVER:
-            break;
-
-        default:
-            G_OBJECT_WARN_INVALID_PROPERTY_ID(gobject, prop_id, pspec);
-
-            break;
-    }
-}
-
-static void
-matrix_client_get_property(GObject *gobject,
-                           guint prop_id,
-                           GValue *value,
-                           GParamSpec *pspec)
-{
-    switch (prop_id) {
-        case PROP_HOMESERVER:
-            break;
-
-        default:
-            G_OBJECT_WARN_INVALID_PROPERTY_ID(gobject, prop_id, pspec);
-
-            break;
-    }
-}
-
-static void
-matrix_client_class_init(MatrixClientClass *klass)
-{
-    GObjectClass *gobject_class = G_OBJECT_CLASS(klass);
-
-    gobject_class->set_property = matrix_client_set_property;
-    gobject_class->get_property = matrix_client_get_property;
-    gobject_class->finalize = matrix_client_finalize;
-    gobject_class->dispose = matrix_client_dispose;
-
-    /**
-     * MatrixClient:homeserver:
-     *
-     * The address of the home server to connect to.
-     */
-    obj_properties[PROP_HOMESERVER] = g_param_spec_string(
-            "homeserver", "Home server",
-            "Matrix.org home server to connect to",
-            NULL,
-            G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
-
-    /**
-     * MatrixClient:token:
-     *
-     * The token to use for authorization.
-     */
-    obj_properties[PROP_TOKEN] = g_param_spec_string(
-            "token", "Token",
-            "Authentication token to use",
-            NULL,
-            G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
-
-    g_object_class_install_properties(gobject_class,
-                                      N_PROPERTIES,
-                                      obj_properties);
-}
-
-static void
-matrix_client_init(MatrixClient *client)
-{
-    MatrixClientPrivate *priv = matrix_client_get_instance_private(client);
-
-    priv->api = NULL;
 }
 
 /**
- * matrix_client_new:
+ * matrix_client_login_with_password:
- * @homeserver: the home server to connect to
+ * @client: a #MatrixClient
- * @token: (allow-none): the authentication token to use
+ * @username: the username to login with
+ * @password: the password to use
  *
- * Creates a new #MatrixClient instance for the specified home
+ * Authenticate with the Matrix.org server with a username and
- * server. The token, if specified, will be used for authorization
+ * password.
- * throughout communication with that server. The token gets
- * autogenerated by matrix_client_login_password() and
- * matrix_client_register_password(). No other communication is
- * allowed with the server before the token is set.
- *
- * Returns: (transfer full): a new #MatrixClient instance
  */
-MatrixClient *
+void
-matrix_client_new(const gchar *homeserver, const gchar *token)
+matrix_client_login_with_password(MatrixClient *client,
+                                  const gchar *username,
+                                  const gchar *password)
 {
-    return g_object_new(MATRIX_TYPE_CLIENT,
+    g_return_if_fail(MATRIX_IS_CLIENT(client));
-                        "homeserver", homeserver,
+
-                        "token", token,
+    MATRIX_CLIENT_GET_IFACE(client)
-                        NULL);
+        ->login_with_password(client, username, password);
+}
+
+/**
+ * matrix_client_register_with_password:
+ * @client: a #MatrixClient
+ * @username: (allow-none): the username to register. If omitted, the
+ *            server will generate one
+ * @password: the password to use with the registration
+ *
+ * Register @username with the homeserver.
+ */
+void
+matrix_client_register_with_password(MatrixClient *client,
+                                     const gchar *username,
+                                     const gchar *password)
+{
+    g_return_if_fail(MATRIX_IS_CLIENT(client));
+
+    MATRIX_CLIENT_GET_IFACE(client)
+        ->register_with_password(client, username, password);
+}
+
+/**
+ * matrix_client_logout:
+ * @client: a #MatrixClient
+ *
+ * Logout from the homeserver. As Matrix.org doesn’t have such an
+ * option, this cancels all ongoing requests and clears the
+ * authentication data (e.g. tokens).
+ */
+void
+matrix_client_logout(MatrixClient *client)
+{
+    g_return_if_fail(MATRIX_IS_CLIENT(client));
+
+    MATRIX_CLIENT_GET_IFACE(client)
+        ->logout(client);
+}
+
+/**
+ * matrix_client_refresh_token:
+ * @client: a #MatrixClient
+ *
+ * Request a new authentication token from the server.
+ */
+void
+matrix_client_refresh_token(MatrixClient *client)
+{
+    g_return_if_fail(MATRIX_IS_CLIENT(client));
+
+    MATRIX_CLIENT_GET_IFACE(client)
+        ->refresh_token(client);
+}
+
+/**
+ * matrix_client_begin_polling:
+ * @client: a #MatrixClient
+ *
+ * Begin polling the event stream. For each incoming event,
+ * MatrixClient:live-event is fired.
+ */
+void
+matrix_client_begin_polling(MatrixClient *client)
+{
+    g_return_if_fail(MATRIX_IS_CLIENT(client));
+
+    MATRIX_CLIENT_GET_IFACE(client)
+        ->begin_polling(client);
+}
+
+/**
+ * matrix_client_stop_polling:
+ * @client: a #MatrixClient
+ * @cancel_ongoing: if %TRUE, ongoing requests will be cancelled, too
+ *
+ * Stop polling the event stream. If @cancel_ongoing is %TRUE, ongoing
+ * requests will be cancelled, too.
+ */
+void
+matrix_client_stop_polling(MatrixClient *client, gboolean cancel_ongoing)
+{
+    g_return_if_fail(MATRIX_IS_CLIENT(client));
+
+    MATRIX_CLIENT_GET_IFACE(client)
+        ->stop_polling(client, cancel_ongoing);
 }

src/matrix-client.h

@@ -25,19 +25,35 @@ G_BEGIN_DECLS
 
 #define MATRIX_TYPE_CLIENT         (matrix_client_get_type())
 #define MATRIX_CLIENT(o)           (G_TYPE_CHECK_INSTANCE_CAST((o), MATRIX_TYPE_CLIENT, MatrixClient))
-#define MATRIX_CLIENT_CLASS(k)     (G_TYPE_CHECK_CLASS_CAST((k), MATRIX_TYPE_CLIENT, MatrixClientClass))
 #define MATRIX_IS_CLIENT(o)        (G_TYPE_CHECK_INSTANCE_TYPE((o), MATRIX_TYPE_CLIENT))
-#define MATRIX_IS_CLIENT_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE((k), MATRIX_TYPE_CLIENT))
+#define MATRIX_CLIENT_GET_IFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE((o), MATRIX_TYPE_CLIENT, MatrixClientInterface))
-#define MATRIX_CLIENT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS((o), MATRIX_TYPE_CLIENT, MatrixClientClass))
 
+typedef struct _MatrixClientInterface MatrixClientInterface;
 typedef struct _MatrixClient          MatrixClient;
-typedef struct _MatrixClientClass MatrixClientClass;
 
-struct _MatrixClient {
+struct _MatrixClientInterface {
+    /*< private >*/
     /* Parent instance structure */
-    GObject parent_instance;
+    GTypeInterface g_iface;
 
+    /*< public >*/
     /* Instance members */
+
+    /* Virtual table */
+    void (*login_with_password)(MatrixClient *client,
+                                const gchar *username,
+                                const gchar *password);
+    void (*register_with_password)(MatrixClient *client,
+                                   const gchar *username,
+                                   const gchar *password);
+    void (*logout)(MatrixClient *client);
+    void (*refresh_token)(MatrixClient *client);
+
+    void (*begin_polling)(MatrixClient *client);
+    void (*stop_polling)(MatrixClient *client, gboolean cancel_ongoing);
+
+    void (*get_room)(MatrixClient *client, const gchar *room_id_or_alias);
+    void (*get_user)(MatrixClient *client, const gchar *user_id);
 };
 
 struct _MatrixClientClass {
@@ -46,7 +62,22 @@ struct _MatrixClientClass {
 };
 
 GType matrix_client_get_type(void) G_GNUC_CONST;
-MatrixClient *matrix_client_new(const gchar *homeserver, const gchar *token);
+
+void matrix_client_login_with_password(MatrixClient *client,
+                                       const gchar *username,
+                                       const gchar *password);
+void matrix_client_register_with_password(MatrixClient *client,
+                                          const gchar *username,
+                                          const gchar *password);
+void matrix_client_logout(MatrixClient *client);
+void matrix_client_refresh_token(MatrixClient *client);
+
+void matrix_client_begin_polling(MatrixClient *client);
+void matrix_client_stop_polling(MatrixClient *client, gboolean cancel_ongoing);
+
+void matrix_client_get_room(MatrixClient *client,
+                            const gchar *room_id_or_alias);
+void matrix_client_get_user(MatrixClient *client, const gchar *user_id);
 
 G_END_DECLS