/*
 * This file is part of matrix-glib-sdk
 *
 * matrix-glib-sdk is free software: you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation, either
 * version 3 of the License, or (at your option) any later version.
 *
 * matrix-glib-sdk is distributed in the hope that it will be
 * useful, but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with matrix-glib-sdk. If not, see
 * <http://www.gnu.org/licenses/>.
 */

#include "matrix-api.h"

/**
 * SECTION:matrix-api
 * @title: MatrixAPI
 * @short_description: An interface for actual API implementations,
 *                     like #MatrixHTTPAPI
 *
 * This interface provides a skeleton for all API functionality for
 * client communication with a Matrix.org homeserver.
 **/

/**
 * MatrixAPI:
 *
 * An opaque pointer type.
 **/

/**
 * MatrixAPIInterface:
 * @get_token: virtual function for matrix_api_get_token()
 * @set_token: virtual function for matrix_api_set_token()
 * @get_refresh_token: virtual function for matrix_api_get_refresh_token()
 * @set_refresh_token: virtual function for matrix_api_set_refresh_token()
 * @get_user_id: virtual function for matrix_api_get_user_id()
 * @get_homeserver: virtual function for matrix_api_get_homeserver()
 * @media_download: virtual function for matrix_api_media_download()
 * @media_thumbnail: virtual function for matrix_api_media_thumbnail()
 * @media_upload: virtual function for matrix_api_media_upload()
 * @get_presence_list: virtual function for matrix_api_get_presence_list()
 * @update_presence_list: virtual function for matrix_api_update_presence_list()
 * @get_user_presence: virtual function for matrix_api_get_user_presence()
 * @set_user_presence: virtual function for matrix_api_set_user_presence()
 * @update_pusher: virtual function for matrix_api_update_pusher()
 * @get_pushers: virtual function for matrix_api_get_pushers()
 * @delete_pusher: virtual function for matrix_api_delete_pusher()
 * @get_pusher: virtual function for matrix_api_get_pusher()
 * @add_pusher: virtual function for matrix_api_add_pusher()
 * @toggle_pusher: virtual function for matrix_api_toggle_pusher()
 * @create_room: virtual function for matrix_api_create_room()
 * @delete_room_alias: virtual function for matrix_api_delete_room_alias()
 * @get_room_id: virtual function for matrix_api_get_room_id()
 * @create_room_alias: virtual function for matrix_api_create_room_alias()
 * @list_public_rooms: virtual function for matrix_api_list_public_rooms()
 * @ban_user: virtual function for matrix_api_ban_user()
 * @forget_room: virtual function for matrix_api_forget_room()
 * @invite_user_3rdparty: virtual function for matrix_api_invite_user_3rdparty()
 * @invite_user: virtual function for matrix_api_invite_user()
 * @join_room: virtual function for matrix_api_join_room()
 * @leave_room: virtual function for matrix_api_leave_room()
 * @event_stream: virtual function for matrix_api_event_stream()
 * @get_event: virtual function for matrix_api_get_event()
 * @initial_sync: virtual function for matrix_api_initial_sync()
 * @get_event_context: virtual function for matrix_api_get_event_context()
 * @initial_sync_room: virtual function for matrix_api_initial_sync_room()
 * @list_room_members: virtual function for matrix_api_list_room_members()
 * @list_room_messages: virtual function for matrix_api_list_room_messages()
 * @send_event_receipt: virtual function for matrix_api_send_event_receipt()
 * @redact_event: virtual function for matrix_api_redact_event()
 * @send_message_event: virtual function for matrix_api_send_message_event()
 * @get_room_state: virtual function for matrix_api_get_room_state()
 * @send_room_event: virtual function for matrix_api_send_room_event()
 * @notify_room_typing: virtual function for matrix_api_notify_room_typing()
 * @sync: virtual function for matrix_api_sync()
 * @create_filter: virtual function for matrix_api_create_filter()
 * @download_filter: virtual function for matrix_api_download_filter()
 * @whois: virtual function for matrix_api_whois()
 * @versions: virtual function for matrix_api_versions()
 * @login: virtual function for matrix_api_login()
 * @token_refresh: virtual function for matrix_api_token_refresh()
 * @get_3pids: virtual function for matrix_api_get_3pids()
 * @add_3pid: virtual function for matrix_api_add_3pid()
 * @change_password: virtual function for matrix_api_change_password()
 * @get_profile: virtual function for matrix_api_get_profile()
 * @get_avatar_url: virtual function for matrix_api_get_avatar_url()
 * @set_avatar_url: virtual function for matrix_api_set_avatar_url()
 * @get_display_name: virtual function for matrix_api_get_display_name()
 * @set_display_name: virtual function for matrix_api_set_display_name()
 * @register_account: virtual function for matrix_api_register_account()
 * @set_account_data: virtual function for matrix_api_set_account_data()
 * @get_room_tags: virtual function for matrix_api_get_room_tags()
 * @delete_room_tag: virtual function for matrix_api_delete_room_tag()
 * @add_room_tag: virtual function for matrix_api_add_room_tag()
 * @get_turn_server: virtual function for matrix_api_get_turn_server()
 *
 * The interface vtable for #MatrixAPI
 */

/**
 * MatrixAPICallback:
 * @api: A #MatrixAPI implementation
 * @content_type: the content_type of the response
 * @json_content: (allow-none): the JSON content of the response, as a
 *                #JsonNode
 * @raw_content: (allow-none): the raw content of the response
 * @user_data: User data specified when calling original request function
 * @err: a #GError. It will hold any errors from the underlying API
 *       (including communication or type errors)
 *
 * A callback function to use with API calls. Either @json_content or
 * @raw_content will be set.
 */

G_DEFINE_INTERFACE(MatrixAPI, matrix_api, G_TYPE_OBJECT);

static void
matrix_api_default_init(MatrixAPIInterface *iface)
{
    /**
     * MatrixAPI:token:
     *
     * The token to use for authorization. The matrix_api_login() and
     * matrix_api_register_account() calls must set this
     * automatically.
     */
    g_object_interface_install_property(
            iface,
            g_param_spec_string("token", "Authorization token",
                                "The authorization token to use in requests",
                                NULL,
                                G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));

    /**
     * MatrixAPI:refresh-token:
     *
     * The token to use for refreshing the authorization token. It is
     * issued by the server after a successful registration, login,
     * and token refresh, but can also be changed with
     * matrix_api_set_refresh_token() (or setting this property).
     */
    g_object_interface_install_property(
            iface,
            g_param_spec_string("refresh-token", "Refresh token",
                                "The token issued by the server for authorization token renewal",
                                NULL,
                                G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));

    /**
     * MatrixAPI:user-id:
     *
     * The Matrix user ID that is currently authenticated to the
     * server. It is set by the registration and login processes
     * automatically, and cannot be set from outside.
     */
    g_object_interface_install_property(
            iface,
            g_param_spec_string("user-id", "User ID",
                                "The Matrix user ID that is authenticated to the server",
                                NULL,
                                G_PARAM_READABLE));

    /**
     * MatrixAPI:homeserver:
     *
     * The Matrix home server, as it calls itself. It is filled
     * automatically by login and register calls.
     */
    g_object_interface_install_property(
            iface,
            g_param_spec_string("homeserver", "Homeserver",
                                "The home server, as it calls itself",
                                NULL,
                                G_PARAM_READABLE));
}

/* Property getters and setters */

/**
 * matrix_api_get_token:
 * @api: a #MatrixAPI implementation
 *
 * Get the authorization token currently set. See
 * matrix_api_set_token() for limitations.
 *
 * Returns: (transfer none) (allow-none): the authorization token that
 *          will be used in subsequent requests, or %NULL if none
 *          set. The returned value is owned by the @api object and
 *          should not be freed nor modified
 */
const gchar *
matrix_api_get_token(MatrixAPI *api)
{
    g_return_val_if_fail(MATRIX_IS_API(api), NULL);

    return MATRIX_API_GET_IFACE(api)
        ->get_token(api);
}

/**
 * matrix_api_set_token:
 * @api: a #MatrixAPI implementation
 * @token: the authorization token to set
 *
 * Set the authorization token to use in subsequent requests.
 *
 * <warning><para>Some implementations, like #MatrixHTTPAPI, use
 * asynchronous requests. This means that pending requests will use
 * the old token and thus, may fail because of this.</para></warning>
 */
void
matrix_api_set_token(MatrixAPI *api, const gchar *token)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->set_token(api, token);
}

/**
 * matrix_api_get_refresh_token:
 * @api: a #MatrixAPI implementation
 *
 * Get the refresh token currently set. See matrix_api_set_token() for
 * limitations.
 *
 * Returns: (transfer none) (allow-none): the refresh token to be used
 *          for authorization token refreshment, or %NULL if there is
 *          none set. The returned value is owned by the @api object
 *          and should not be freed nor modified
 */
const gchar *
matrix_api_get_refresh_token(MatrixAPI *api)
{
    g_return_val_if_fail(MATRIX_IS_API(api), NULL);

    return MATRIX_API_GET_IFACE(api)
        ->get_refresh_token(api);
}

/**
 * matrix_api_set_refresh_token:
 * @api: a #MatrixAPI implementation
 * @refresh_token: the refresh token to set
 *
 * Set the refresh token to be used in subsequent requests. See
 * matrix_api_set_token() for limitations.
 */
void
matrix_api_set_refresh_token(MatrixAPI *api, const gchar *refresh_token)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->set_refresh_token(api, refresh_token);
}

/**
 * matrix_api_get_user_id:
 * @api: a #MatrixAPI implementation
 *
 * Get the Matrix user ID that is currently authenticated with the
 * server.
 *
 * Returns: (transfer none) (allow-none): the Matrix user ID
 *          authenticated by the last successful register or login
 *          call (ie. matrix_api_login() or
 *          matrix_api_register_account()). If no user is
 *          authenticated, this function returns %NULL. The returned
 *          value is owned by the @api object and should not be freed
 *          nor modified
 */
const gchar *
matrix_api_get_user_id(MatrixAPI *api)
{
    g_return_val_if_fail(MATRIX_IS_API(api), NULL);

    return MATRIX_API_GET_IFACE(api)
        ->get_user_id(api);
}

/**
 * matrix_api_get_homeserver:
 * @api: a #MatrixAPI implementation
 *
 * Get the homeserver's name, as it calls itself. It gets set
 * automatically by login and register calls, e.g. matrix_api_login()
 * or matrix_api_register_account().
 *
 * Returns: (transfer none) (allow-none): the Matrix homeserver's
 * name, as it calls itself. If no homeserver name is reported yet
 * (e.g. because login or register wasn't called yet), this function
 * returns %NULL.
 */
const gchar *
matrix_api_get_homeserver(MatrixAPI *api)
{
    g_return_val_if_fail(MATRIX_IS_API(api), NULL);

    return MATRIX_API_GET_IFACE(api)
        ->get_homeserver(api);
}

/* Media */

/**
 * matrix_api_media_download:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @server_name: the server name from the <code>mxc://</code> URI (the
 *               authority component)
 * @media_id: the media ID from the <code>mxc://</code> URI (the path
 *            component)
 * @error: return location for a #GError, or %NULL
 *
 * Download content from the content repository.
 */
void
matrix_api_media_download(MatrixAPI *api,
                          MatrixAPICallback callback,
                          gpointer user_data,
                          const gchar *server_name,
                          const gchar *media_id,
                          GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->media_download(api,
                         callback, user_data,
                         server_name, media_id, error);
}

/**
 * matrix_api_media_thumbnail:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @server_name: the server name from the <code>mxc://</code> URI (the
 *               authority component)
 * @media_id: the media ID from the <code>mxc://</code> URI (the path
 *            component)
 * @width: the desired width of the thumbnail, or 0 to use the default
 * @height: the desired height of the thumbnail, or 0 to use the
 *          default
 * @method: the resizing method to use
 * @error: return location for a #GError, or %NULL
 *
 * Download a thumbnail of the content from the content
 * repository. The actual thumbnail may not match the size specified.
 */
void
matrix_api_media_thumbnail(MatrixAPI *api,
                           MatrixAPICallback callback,
                           gpointer user_data,
                           const gchar *server_name,
                           const gchar *media_id,
                           guint width,
                           guint height,
                           MatrixAPIResizeMethod method,
                           GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->media_thumbnail(api,
                          callback, user_data,
                          server_name, media_id,
                          width, height, method,
                          error);
}

/**
 * matrix_api_media_upload:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @content_type: (allow-none): the content type of the file being
 *                uploaded
 * @content: (transfer full): the content to be uploaded
 * @error: return location for a #GError, or %NULL
 *
 * Upload some content to the content repository.
 */
void
matrix_api_media_upload(MatrixAPI *api,
                        MatrixAPICallback callback,
                        gpointer user_data,
                        const gchar *content_type,
                        GByteArray *content,
                        GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->media_upload(api, callback, user_data, content_type, content, error);
}

/* Presence */

/**
 * matrix_api_get_presence_list:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user whose presence list should be retrieved
 * @error: return location for a #GError, or %NULL
 *
 * Retrieve a list of presence events for every user on this list.
 */
void
matrix_api_get_presence_list(MatrixAPI *api,
                             MatrixAPICallback callback,
                             gpointer user_data,
                             const gchar *user_id,
                             GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_presence_list(api, callback, user_data, user_id, error);
}

/**
 * matrix_api_update_presence_list:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user whose presence list is being modified
 * @drop_ids: (element-type utf8): a list of user IDs to remove
 *            from the list
 * @invite_ids: (element-type utf8): a list of user IDs to add to
 *              the list
 * @error: return location for a #GError, or %NULL
 *
 * Add or remove users from the specified user's presence list.
 */
void
matrix_api_update_presence_list(MatrixAPI *api,
                                MatrixAPICallback callback,
                                gpointer user_data,
                                const gchar *user_id,
                                GList *drop_ids,
                                GList *invite_ids,
                                GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->update_presence_list(api,
                               callback, user_data,
                               user_id, drop_ids, invite_ids, error);
}

/**
 * matrix_api_get_user_presence:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user whose presence list is being modified
 * @error: return location for a #GError, or %NULL
 *
 * Get the given user's presence state.
 */
void
matrix_api_get_user_presence(MatrixAPI *api,
                             MatrixAPICallback callback,
                             gpointer user_data,
                             const gchar *user_id,
                             GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_user_presence(api,
                            callback, user_data,
                            user_id, error);
}

/**
 * matrix_api_set_user_presence:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user whose presence list is being modified
 * @presence: the new presence state
 * @status_message: a status message attached to this state
 * @error: return location for a #GError, or %NULL
 *
 * Set the given user's presence. You cannot set the presence of
 * another user.
 */
void
matrix_api_set_user_presence(MatrixAPI *api,
                             MatrixAPICallback callback,
                             gpointer user_data,
                             const gchar *user_id,
                             MatrixAPIPresence presence,
                             const gchar *status_message,
                             GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->set_user_presence(api,
                            callback, user_data,
                            user_id, presence, status_message,
                            error);
}

/* Push notifications */

/**
 * matrix_api_update_pusher:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @pusher: the pusher information
 * @error: return location for a #GError, or %NULL
 *
 * Create, update or delete a pusher for the active user on this
 * homeserver.
 */
void
matrix_api_update_pusher(MatrixAPI *api,
                         MatrixAPICallback callback,
                         gpointer user_data,
                         MatrixAPIPusher *pusher,
                         GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->update_pusher(api,
                        callback, user_data,
                        pusher, error);
}

/**
 * matrix_api_get_pushers:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @error: return location for a #GError, or %NULL
 *
 * Retrieve all push rulesets.
 */
void
matrix_api_get_pushers(MatrixAPI *api,
                       MatrixAPICallback callback,
                       gpointer user_data,
                       GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_pushers(api, callback, user_data, error);
}

/**
 * matrix_api_delete_pusher:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @scope: either <code>global</code> to specify global rules, or
 *         <code>device/&lt;profile tag&gt;</code> for rules for a
 *         given <code>profile tag</code>.
 * @kind: the kind of rule
 * @rule_id: an identifier for the rule
 * @error: return location for a #GError, or %NULL
 *
 * Delete a push rule.
 */
void
matrix_api_delete_pusher(MatrixAPI *api,
                         MatrixAPICallback callback,
                         gpointer user_data,
                         const gchar *scope,
                         MatrixAPIPusherKind kind,
                         const gchar *rule_id,
                         GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->delete_pusher(api,
                        callback, user_data,
                        scope, kind, rule_id, error);
}

/**
 * matrix_api_get_pusher:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @scope: either <code>global</code> to specify global rules, or
 *         <code>device/&lt;profile tag&gt;</code> for rules for a
 *         given <code>profile tag</code>.
 * @kind: the kind of rule
 * @rule_id: an identifier for the rule
 * @error: return location for a #GError, or %NULL
 *
 * Retrieve a specific push rule.
 */
void
matrix_api_get_pusher(MatrixAPI *api,
                      MatrixAPICallback callback,
                      gpointer user_data,
                      const gchar *scope,
                      MatrixAPIPusherKind kind,
                      const gchar *rule_id,
                      GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_pusher(api,
                     callback, user_data,
                     scope, kind, rule_id, error);
}

/**
 * matrix_api_add_pusher:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @scope: either <code>global</code> to specify global rules, or
 *         <code>device/&lt;profile tag&gt;</code> for rules for a
 *         given <code>profile tag</code>.
 * @kind: the kind of rule
 * @rule_id: an identifier for the rule
 * @before: (allow-none): make the new rule the next-most important
 *          than this rule ID
 * @after: (allow-none): make the new rule the next-less important
 *         than this rule ID
 * @actions: (element-type utf8): the actions to perform when the
 *           conditions for this rule are met
 * @conditions: (element-type MatrixAPIPusherConditionKind) (allow-none):
 *              the conditions that must hold true for an event for a
 *              rule to be applied. A rule with no conditions always
 *              matches
 * @error: return location for a #GError, or %NULL
 *
 * Add or change a push rule.
 */
void
matrix_api_add_pusher(MatrixAPI *api,
                      MatrixAPICallback callback,
                      gpointer user_data,
                      const gchar *scope,
                      MatrixAPIPusherKind kind,
                      const gchar *rule_id,
                      const gchar *before,
                      const gchar *after,
                      GList *actions,
                      GList *conditions,
                      GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->add_pusher(api,
                     callback, user_data,
                     scope, kind, rule_id, before, after,
                     actions, conditions,
                     error);
}

/**
 * matrix_api_toggle_pusher:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): a function to call when the
 *            request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @scope: either <code>global</code> to specify global rules, or
 *         <code>device/&lt;profile tag&gt;</code> for rules for a
 *         given <code>profile tag</code>.
 * @kind: the kind of rule
 * @rule_id: an identifier for the rule
 * @enabled: if %TRUE, the rule will be enabled, otherwise it gets
 *           disabled
 * @error: return location for a #GError, or %NULL
 *
 * Enable or disable the specified push rule.
 */
void matrix_api_toggle_pusher(MatrixAPI *api,
                              MatrixAPICallback callback,
                              gpointer user_data,
                              const gchar *scope,
                              MatrixAPIPusherKind kind,
                              const gchar *rule_id,
                              gboolean enabled,
                              GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->toggle_pusher(api,
                        callback, user_data,
                        scope, kind, rule_id, enabled, error);
}

/* Room creation */

/**
 * matrix_api_create_room:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): the function to call when
 *            the request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @preset: a room preset to use
 * @room_name: (allow-none): the desired display name for the room
 * @room_alias: (allow-none): an alias of the room
 * @topic: (allow-none): the topic of the room
 * @visibility: the initial visibility of the room
 * @creation_content: (allow-none): extra keys to be added to the
 *                    content of m.room.create
 * @initial_state: (element-type MatrixAPIStateEvent) (allow-none): A
 *                 list of state events to set in the new room
 * @invitees: (element-type utf8) (allow-none): list of user IDs to
 *            invite to the new room
 * @invite_3pids: (element-type MatrixAPI3PidCredential) (allow-none):
 *                 a list of 3rd party credentials to invite to the
 *                 new room
 * @error: return location for a #GError, or %NULL
 *
 * Create a new room with the given name and invite the users in
 * @invitees.
 */
void
matrix_api_create_room(MatrixAPI *api,
                       MatrixAPICallback callback,
                       gpointer user_data,
                       MatrixAPIRoomPreset preset,
                       const gchar *room_name,
                       const gchar *room_alias,
                       const gchar *topic,
                       MatrixAPIRoomVisibility visibility,
                       JsonNode *creation_content,
                       GList *initial_state,
                       GList *invitees,
                       GList *invite_3pids,
                       GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->create_room(api, callback, user_data,
                      preset, room_name, room_alias, topic,
                      visibility, creation_content,
                      initial_state, invitees, invite_3pids,
                      error);
}

/* Room directory */

/**
 * matrix_api_delete_room_alias:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): the function to call when
 *            the request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_alias: the alias name to remove
 * @error: return location for a #GError, or %NULL
 *
 * Remove the mapping of @room_alias to its room ID
 *
 * Servers may choose to implement additional access control checks
 * here, for instance that room aliases can only be deleted by their
 * creator or a server administrator.
 */
void
matrix_api_delete_room_alias(MatrixAPI *api,
                             MatrixAPICallback callback,
                             gpointer user_data,
                             const gchar *room_alias,
                             GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->delete_room_alias(api, callback, user_data, room_alias, error);
}

/**
 * matrix_api_get_room_id:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): the function to call when
 *            the request is finished
 * @user_data: (closure) (allow-none): user data to pass to the callback function
 * @room_alias: the room alias
 * @error: return location for a #GError, or %NULL
 *
 * Get the room ID corresponding to this room alias.
 */
void
matrix_api_get_room_id(MatrixAPI *api,
                       MatrixAPICallback callback,
                       gpointer user_data,
                       const gchar *room_alias,
                       GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_room_id(api, callback, user_data, room_alias, error);
}

/**
 * matrix_api_create_room_alias:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): the function to call when
 *            the request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room ID to add this alias to
 * @room_alias: the room alias to set
 * @error: return location for a #GError, or %NULL
 *
 * Create a new mapping from room alias to room ID.
 */
void
matrix_api_create_room_alias(MatrixAPI *api,
                             MatrixAPICallback callback,
                             gpointer user_data,
                             const gchar *room_id,
                             const gchar *room_alias,
                             GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->create_room_alias(api,
                            callback, user_data,
                            room_id, room_alias,
                            error);
}

/* Room discovery */

/**
 * matrix_api_list_public_rooms:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async) (allow-none): the function to call when
 *            the request is finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @error: return location for a #GError, or %NULL
 *
 * List the public rooms on the server.
 */
void
matrix_api_list_public_rooms(MatrixAPI *api,
                             MatrixAPICallback callback,
                             gpointer user_data,
                             GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->list_public_rooms(api, callback, user_data, error);
}

/* Room membership */

/**
 * matrix_api_ban_user:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room ID where the user should be banned
 * @user_id: the user ID to ban
 * @reason: (allow-none): the reason of the ban
 * @error: return location for a #GError, or %NULL
 *
 * Ban the specified user from the specified room. An optional reason
 * can be specified. If @room_id or @user_id is %NULL, this
 * function returns immediately, and fills @error with
 * %MATRIX_API_ERROR_INCOMPLETE.
 */
void
matrix_api_ban_user(MatrixAPI *api,
                    MatrixAPICallback callback,
                    gpointer user_data,
                    const gchar *room_id,
                    const gchar *user_id,
                    const gchar *reason,
                    GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    if (!room_id || !user_id) {
        g_set_error(error,
                    MATRIX_API_ERROR, MATRIX_API_ERROR_INCOMPLETE,
                    "room_id and user_id must be set.");

        return;
    }

    MATRIX_API_GET_IFACE(api)
        ->ban_user(api, callback, user_data, room_id, user_id, reason, error);
}

/**
 * matrix_api_forget_room:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room ID to forget
 * @error: return location for a #GError, or %NULL
 *
 * Stop the requesting user remembering about a particular room.
 *
 * In general, history is a first class citizen in Matrix. After this
 * API is called, however, a user will no longer be able to retrieve
 * history for this room. If all users on a homeserver forget a room,
 * the room is eligible for deletion from that homeserver.
 *
 * If the user is currently joined to the room, they will implicitly
 * leave the room as part of this API call.
 *
 * If @room_id is %NULL, this function returns immediately, and fills
 * @error with %MATRIX_API_ERROR_INCOMPLETE.
 */
void
matrix_api_forget_room(MatrixAPI *api,
                       MatrixAPICallback callback,
                       gpointer user_data,
                       const gchar *room_id,
                       GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    if (!room_id) {
        g_set_error(error,
                    MATRIX_API_ERROR, MATRIX_API_ERROR_INCOMPLETE,
                    "room_id must be set.");

        return;
    }

    MATRIX_API_GET_IFACE(api)
        ->forget_room(api, callback, user_data, room_id, error);
}

/**
 * matrix_api_invite_user_3rdparty:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room ID to which to invite the user
 * @credential: (transfer none): a #MatrixAPI3PidCredential that
 *              identifies a user to invite
 * @error: return location for a #GError, or %NULL
 *
 * Invite a user to the room by a 3rd party identifier. They do not
 * start participating in the room until they actually join the room.
 *
 * If the identity server does not know a Matrix user identifier for
 * the passed third party identifier, the homeserver will issue an
 * invitation which can be accepted upon providing proof of ownership
 * of the third party identifier.
 */
void matrix_api_invite_user_3rdparty(MatrixAPI *api,
                                     MatrixAPICallback callback,
                                     gpointer user_data,
                                     const gchar *room_id,
                                     MatrixAPI3PidCredential *credential,
                                     GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->invite_user_3rdparty(api,
                               callback, user_data,
                               room_id, credential,
                               error);
}

/**
 * matrix_api_invite_user:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room ID to invite the user to
 * @user_id: the user ID to invite
 * @error: return location for a #GError, or %NULL
 *
 * Invite a user to a room.
 */
void
matrix_api_invite_user(MatrixAPI *api,
                       MatrixAPICallback callback,
                       gpointer user_data,
                       const gchar *room_id,
                       const gchar *user_id,
                       GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->invite_user(api, callback, user_data, room_id, user_id, error);
}

/**
 * matrix_api_join_room:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room ID to join to
 * @error: return location for a #GError, or %NULL
 *
 * Join a room.
 */
void
matrix_api_join_room(MatrixAPI *api,
                     MatrixAPICallback callback,
                     gpointer user_data,
                     const gchar *room_id,
                     GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->join_room(api, callback, user_data, room_id, error);
}

/**
 * matrix_api_leave_room:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room ID to kick the user from
 * @error: return location for a #GError, or %NULL
 *
 * Leave a room
 */
void
matrix_api_leave_room(MatrixAPI *api,
                      MatrixAPICallback callback,
                      gpointer user_data,
                      const gchar *room_id,
                      GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->leave_room(api, callback, user_data, room_id, error);
}

/* Room participation */

/**
 * matrix_api_event_stream:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @from_token: (allow-none): events will be listed from this token
 * @timeout: timeout of the request
 * @error: return location for a #GError, or %NULL
 *
 * Get the event stream, optionally beginning from @from_token.
 */
void
matrix_api_event_stream(MatrixAPI *api,
                        MatrixAPICallback callback,
                        gpointer user_data,
                        const gchar *from_token,
                        gulong timeout,
                        GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->event_stream(api, callback, user_data, from_token, timeout, error);
}

/**
 * matrix_api_get_event:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @event_id: the event ID to get
 * @error: return location for a #GError, or %NULL
 *
 * Get a single event by event ID.
 */
void
matrix_api_get_event(MatrixAPI *api,
                     MatrixAPICallback callback,
                     gpointer user_data,
                     const gchar *event_id,
                     GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_event(api, callback, user_data, event_id, error);
}

/**
 * matrix_api_initial_sync:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @limit: the maximum number of events to get
 * @archived: whether to include rooms that the user has left
 * @error: return location for a #GError, or %NULL
 *
 * perform an initial sync of events
 */
void
matrix_api_initial_sync(MatrixAPI *api,
                        MatrixAPICallback callback,
                        gpointer user_data,
                        guint limit,
                        gboolean archived,
                        GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->initial_sync(api, callback, user_data, limit, archived, error);
}

/**
 * matrix_api_get_event_context:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room to get events from
 * @event_id: the event to get context around
 * @limit: the maximum number of events to get. If 0, a default value
 *         is used (10, according to the specification)
 * @error: return location for a #GError, or %NULL
 *
 * Gets a number of events that happened just before and after the
 * specified event.
 */
void
matrix_api_get_event_context(MatrixAPI *api,
                             MatrixAPICallback callback,
                             gpointer user_data,
                             const gchar *room_id,
                             const gchar *event_id,
                             guint limit,
                             GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_event_context(api,
                            callback, user_data,
                            room_id, event_id, limit, error);
}

/**
 * matrix_api_initial_sync_room:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room to get the data for
 * @error: return location for a #GError, or %NULL
 *
 * Get a copy of the current state and the most recent messages in a
 * room.
 */
void
matrix_api_initial_sync_room(MatrixAPI *api,
                             MatrixAPICallback callback,
                             gpointer user_data,
                             const gchar *room_id,
                             GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->initial_sync_room(api, callback, user_data, room_id, error);
}

/**
 * matrix_api_list_room_members:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room to get the member events for
 * @error: return location for a #GError, or %NULL
 *
 * Get the list of members for a room.
 */
void
matrix_api_list_room_members(MatrixAPI *api,
                             MatrixAPICallback callback,
                             gpointer user_data,
                             const gchar *room_id,
                             GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->list_room_members(api, callback, user_data, room_id, error);
}

/**
 * matrix_api_list_room_messages:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room to get the events for
 * @from_token: the token to start returning events from. This token
 *              can be obtained by calling matrix_api_initial_sync()
 *              or matrix_api_initial_sync_room()
 * @direction: the direction of the returned events
 * @limit: the maximum number of events to return. If 0, a default
 *         value will be used (10, according to the specification
 * @error: return location for a #GError, or %NULL
 *
 * Get a list of message and state events for a room.
 */
void
matrix_api_list_room_messages(MatrixAPI *api,
                              MatrixAPICallback callback,
                              gpointer user_data,
                              const gchar *room_id,
                              const gchar *from_token,
                              MatrixAPIEventDirection direction,
                              guint limit,
                              GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->list_room_messages(api,
                             callback, user_data,
                             room_id, from_token, direction, limit,
                             error);
}

/**
 * matrix_api_send_event_receipt:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room in which to send the event
 * @receipt_type: type of the receipt
 * @event_id: the event ID to acknowledge up to
 * @receipt: extra receipt information to attach. Note that the server
 *           will automatically attach the <code>ts</code> field
 * @error: return location for a #GError, or %NULL
 *
 * Update the marker for the given receipt type to the event ID specified.
 */
void
matrix_api_send_event_receipt(MatrixAPI *api,
                              MatrixAPICallback callback,
                              gpointer user_data,
                              const gchar *room_id,
                              MatrixAPIReceiptType receipt_type,
                              const gchar *event_id,
                              JsonNode *receipt,
                              GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->send_event_receipt(api,
                             callback, user_data,
                             room_id, receipt_type, event_id, receipt,
                             error);
}

/**
 * matrix_api_redact_event:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room from which to redact the event
 * @event_id: the event ID to acknowledge up to
 * @txn_id: the transaction ID for this event. Clients should generate
 *          a unique ID; it will be used by the server to ensure
 *          idempotency of requests
 * @reason: (allow-none): the reason for the event being redacted
 * @error: return location for a #GError, or %NULL
 *
 * Strip all information out of an event which isn't critical to the
 * integrity of the server-side representation of the room. This
 * cannot be undone.
 *
 * Users may redact their own events, and any user with a power level
 * greater than or equal to <code>redact</code> power level of the
 * room may redact events there.
 */
void
matrix_api_redact_event(MatrixAPI *api,
                        MatrixAPICallback callback,
                        gpointer user_data,
                        const gchar *room_id,
                        const gchar *event_id,
                        const gchar *txn_id,
                        const gchar *reason,
                        GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->redact_event(api,
                       callback, user_data,
                       room_id, event_id, txn_id, reason,
                       error);
}

/**
 * matrix_api_send_message_event:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room to send the event to
 * @event_type: the type of event to send
 * @txn_id: the transaction ID for this event. Clients should generate
 *          a unique ID; it will be used by the server to ensure
 *          idempotency of requests
 * @content: (transfer full): the content of the event as a #JsonNode
 * @error: return location for a #GError, or %NULL
 *
 * Send a message event to the room.
 */
void
matrix_api_send_message_event(MatrixAPI *api,
                              MatrixAPICallback callback,
                              gpointer user_data,
                              const gchar *room_id,
                              const gchar *event_type,
                              const gchar *txn_id,
                              JsonNode *content,
                              GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->send_message_event(api,
                             callback, user_data,
                             room_id,
                             event_type, txn_id,
                             content, error);
}

/**
 * matrix_api_get_room_state:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room ID to get a state for
 * @event_type: (allow-none): the type of state to look up
 * @state_key: (allow-none): the key of the state to look up. If
 *             @event_type is %NULL, this parameter is ignored
 * @error: return location for a #GError, or %NULL
 *
 * Look up the contents of a state event in a room. If both
 * @event_type and @state_key are empty, get a list of state events
 * for that room.
 */
void
matrix_api_get_room_state(MatrixAPI *api,
                          MatrixAPICallback callback,
                          gpointer user_data,
                          const gchar *room_id,
                          const gchar *event_type,
                          const gchar *state_key,
                          GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_room_state(api,
                         callback, user_data,
                         room_id, event_type, state_key, error);
}

/**
 * matrix_api_send_room_event:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @room_id: the room ID to get a state for
 * @event_type: the type of state to look up
 * @state_key: (allow-none): the key of the state to look up. If
 *             @event_type is %NULL, this parameter is ignored
 * @content: (transfer full): the content of the state event
 * @error: return location for a #GError, or %NULL
 *
 * Send a state event to the room. These events will be overwritten if
 * @room_id, @event_type and @state_key all match.
 *
 * This request cannot use transaction IDs.
 *
 * The required fields in the body of the request (@content) vary
 * depending on the type of the event.
 */
void
matrix_api_send_room_event(MatrixAPI *api,
                           MatrixAPICallback callback,
                           gpointer user_data,
                           const gchar *room_id,
                           const gchar *event_type,
                           const gchar *state_key,
                           JsonNode *content,
                           GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->send_room_event(api,
                          callback, user_data,
                          room_id, event_type, state_key, content,
                          error);
}

/**
 * matrix_api_notify_room_typing:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user who has started to type
 * @room_id: the room in which the user is typing
 * @timeout: the length of time in milliseconds to mark this user as
 *           typing
 * @typing: whether the user is typing or not. If %FALSE, @timeout can
 *          be omitted (ie. set to 0)
 * @error: return location for a #GError, or %NULL
 *
 * Tell the server the user is typing for the next @timeout
 * milliseconds. If @typing is %FALSE, it tells the server that the
 * user stopped typing.
 */
void
matrix_api_notify_room_typing(MatrixAPI *api,
                              MatrixAPICallback callback,
                              gpointer user_data,
                              const gchar *user_id,
                              const gchar *room_id,
                              guint timeout,
                              gboolean typing,
                              GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->notify_room_typing(api,
                             callback, user_data,
                             user_id, room_id, timeout, typing,
                             error);
}

/**
 * matrix_api_sync:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @filter_id: (allow-none): a filter ID created by the filter API
 *             (e.g. matrix_api_create_filter())
 * @filter: (allow-none): a definition on what events to fetch
 * @since: (allow-none): a point in time to continue a sync from
 * @full_state: if %TRUE, all state events will be returned, even if
 *              @since is not empty. If %FALSE, and @since is not
 *              empty, only states which have changed since the point
 *              indicated by @since will be returned
 * @set_presence: controls whether the client is automatically marked
 *                as online by polling this API.
 * @timeout: the maximum time to poll in milliseconds
 * @error: return location for a #GError, or %NULL
 *
 * Synchronize the client's state with the latest state on the
 * server. Clients should use this API when they first log in to get
 * an initial snapshot of the state on the server and then continue to
 * call this API to get incremental details to the state and to
 * receive new messages.
 *
 * Only one of @filter and @filter_id should be specified, or both of
 * them should be set to %NULL to receive all events.
 */
void
matrix_api_sync(MatrixAPI *api,
                MatrixAPICallback callback,
                gpointer user_data,
                const gchar *filter_id,
                const MatrixAPIFilter *filter,
                const gchar *since,
                gboolean full_state,
                gboolean set_presence,
                gulong timeout,
                GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->sync(api,
               callback, user_data,
               filter_id, filter, since,
               full_state, set_presence, timeout,
               error);
}

/**
 * matrix_api_create_filter:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the ID of the user uploading the filter. An access token
 *           must be present (either specifying one with
 *           matrix_api_set_token() or requested from the server via
 *           matrix_api_register_account() or matrix_api_login().
 * @filter: the filter to upload
 * @error: return location for a #GError, or %NULL
 *
 * Upload a new filter definition to the homeserver. It will return a
 * filter ID that may be used in future requests.
 */
void
matrix_api_create_filter(MatrixAPI *api,
                         MatrixAPICallback callback,
                         gpointer user_data,
                         const gchar *user_id,
                         MatrixAPIFilter *filter,
                         GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->create_filter(api,
                        callback, user_data,
                        user_id, filter,
                        error);
}

/**
 * matrix_api_download_filter:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user ID to download a filter from
 * @filter_id: the filter ID to download
 * @error: return location for a #GError, or %NULL
 *
 * Download a filter.
 */
void
matrix_api_download_filter(MatrixAPI *api,
                           MatrixAPICallback callback,
                           gpointer user_data,
                           const gchar *user_id,
                           const gchar *filter_id,
                           GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->download_filter(api,
                          callback, user_data,
                          user_id, filter_id, error);
}

/* Search */

/* Server administration */

/**
 * matrix_api_whois:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user ID to look up
 * @error: return location for a #GError, or %NULL
 *
 * Get information about a particular user.
 */
void
matrix_api_whois(MatrixAPI *api,
                 MatrixAPICallback callback,
                 gpointer user_data,
                 const gchar *user_id,
                 GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->whois(api, callback, user_data, user_id, error);
}

/**
 * matrix_api_versions:
 * @api: a #MatrixAPI iplementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @error: return location for a #GError, or %NULL
 *
 * Get the versions of the specification supported by the server.
 */
void
matrix_api_versions(MatrixAPI *api,
                    MatrixAPICallback callback,
                    gpointer user_data,
                    GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->versions(api, callback, user_data, error);
}

/* Session management */

/**
 * matrix_api_login:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @login_type: the login type to use
 * @content: (allow-none): parameters to pass for the login request
 * @error: return location for a #GError, or %NULL
 *
 * Attempt to login with type @type. Implementations of this method
 * must set the token property on a successful login.
 */
void
matrix_api_login(MatrixAPI *api,
                 MatrixAPICallback callback,
                 gpointer user_data,
                 const gchar *login_type,
                 const JsonNode *content,
                 GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->login(api, callback, user_data, login_type, content, error);
}

/**
 * matrix_api_token_refresh:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @refresh_token: (allow-none): the refresh token that was issued by
 *                 the server
 * @error: return location for a #GError, or %NULL
 *
 * Exchanges a refresh token for a new access token. This is intended
 * to be used if the access token has expired. If @refresh_token is
 * %NULL, iplementations MUST send the stored refresh token. If it is
 * not pesent (e.g. because login hasn’t happened yet), this function
 * MUST yield an error.
 */
void
matrix_api_token_refresh(MatrixAPI *api,
                         MatrixAPICallback callback,
                         gpointer user_data,
                         const gchar *refresh_token,
                         GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->token_refresh(api, callback, user_data, refresh_token, error);
}

/* User data */

/**
 * matrix_api_get_3pids:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @error: return location for a #GError, or %NULL
 *
 * Get a list of the third party identifiers that a homeserver has
 * associated with the user's account.
 *
 * This is not the same as the list of third party identifiers bound
 * to the user's Matrix ID in Identity Servers.
 *
 * Identifiers in this list may be used by the homeserver as, for
 * example, identifiers to accept to reset the user's account
 * password.
 */
void
matrix_api_get_3pids(MatrixAPI *api,
                     MatrixAPICallback callback,
                     gpointer user_data,
                     GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_3pids(api, callback, user_data, error);
}

/**
 * matrix_api_add_3pid:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @bind_creds: whether the homeserver should also bind this third
 *              party identifier to the account's Matrix ID with the
 *              passed Identity Server.
 * @threepid_creds: the credentials to associate with the account
 * @error: return location for a #GError, or %NULL
 *
 * Add contact information to the user's account.
 */
void
matrix_api_add_3pid(MatrixAPI *api,
                    MatrixAPICallback callback,
                    gpointer user_data,
                    gboolean bind_creds,
                    MatrixAPI3PidCredential *threepid_creds,
                    GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->add_3pid(api, callback, user_data, bind_creds, threepid_creds, error);
}

/**
 * matrix_api_change_password:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @new_password: the new password for the account
 * @error: return location for a #GError, or %NULL
 *
 * Change the active user's password.
 */
void
matrix_api_change_password(MatrixAPI *api,
                           MatrixAPICallback callback,
                           gpointer user_data,
                           const gchar *new_password,
                           GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->change_password(api, callback, user_data, new_password, error);
}

/**
 * matrix_api_get_profile:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user whose profile to get
 * @error: return location for a #GError, or %NULL
 *
 * Get a user's profile.
 */
void
matrix_api_get_profile(MatrixAPI *api,
                       MatrixAPICallback callback,
                       gpointer user_data,
                       const gchar *user_id,
                       GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_profile(api, callback, user_data, user_id, error);
}

/**
 * matrix_api_get_avatar_url:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user whose avatar URL to get
 * @error: return location for a #GError, or %NULL
 *
 * Get the URL of the specified user's avatar.
 */
void
matrix_api_get_avatar_url(MatrixAPI *api,
                          MatrixAPICallback callback,
                          gpointer user_data,
                          const gchar *user_id,
                          GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_avatar_url(api, callback, user_data, user_id, error);
}

/**
 * matrix_api_set_avatar_url:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user whose avatar URL to set
 * @avatar_url: the avatar URL info
 * @error: return location for a #GError, or %NULL
 *
 * Set the user's avatar URL.
 */
void
matrix_api_set_avatar_url(MatrixAPI *api,
                          MatrixAPICallback callback,
                          gpointer user_data,
                          const gchar *user_id,
                          const gchar *avatar_url,
                          GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->set_avatar_url(api, callback, user_data, user_id, avatar_url, error);
}

/**
 * matrix_api_get_display_name:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user whose display name to get
 * @error: return location for a #GError, or %NULL
 *
 * Get the user's display name.
 */
void
matrix_api_get_display_name(MatrixAPI *api,
                            MatrixAPICallback callback,
                            gpointer user_data,
                            const gchar *user_id,
                            GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_display_name(api, callback, user_data, user_id, error);
}

/**
 * matrix_api_set_display_name:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user whose display name to set
 * @display_name: the display name info
 * @error: return location for a #GError, or %NULL
 *
 * Set the user's display name.
 */
void
matrix_api_set_display_name(MatrixAPI *api,
                            MatrixAPICallback callback,
                            gpointer user_data,
                            const gchar *user_id,
                            const gchar *display_name,
                            GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->set_display_name(api,
                           callback, user_data,
                           user_id, display_name, error);
}

/**
 * matrix_api_register_account:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @account_kind: the type of account to register
 * @bind_email: if %TRUE, the server binds the e-mail used for
 *              authentication to the Matrix ID with the ID server
 * @username: (allow-none): the local part of the desired Matrix
 *            ID. If omitted, the server will generate a local part
 * @password: the desired password for the account
 * @error: return location for a #GError, or %NULL
 *
 * Attempt to register with type @login_type. Implementations of this
 * method must set the token property on a successful login.
 */
void
matrix_api_register_account(MatrixAPI *api,
                            MatrixAPICallback callback,
                            gpointer user_data,
                            MatrixAPIAccountKind account_kind,
                            gboolean bind_email,
                            const gchar *username,
                            const gchar *password,
                            GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->register_account(api, callback, user_data, account_kind,
                           bind_email, username, password, error);
}

/**
 * matrix_api_set_account_data:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the user to set account data for. An access token must be
 *           present and be authorized to make requests for this user
 *           ID
 * @room_id: (allow-none): the room to set account data for. If %NULL,
 *           the account data will be set globally
 * @event_type: the event type of the account data to set. Custom
 *              types should be namespaced to avoid clashes
 * @content: (transfer full): the content of the account data
 * @error: return location for a #GError, or %NULL
 *
 * Set some account data for the client. This config is only visible
 * to the user who set the account data. The config will be synced to
 * clients in the top-level account data.
 */
void
matrix_api_set_account_data(MatrixAPI *api,
                            MatrixAPICallback callback,
                            gpointer user_data,
                            const gchar *user_id,
                            const gchar *room_id,
                            const gchar *event_type,
                            JsonNode *content,
                            GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->set_account_data(api,
                           callback, user_data,
                           user_id, room_id, event_type, content, error);
}

/**
 * matrix_api_get_room_tags:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the ID of the user to get the tags for. An access token
 *           must be set, and it must be authorised to make requests
 *           for this user ID
 * @room_id: the room to get tags for
 * @error: return location for a #GError, or %NULL
 *
 * List the tags set by a user on a room.
 */
void
matrix_api_get_room_tags(MatrixAPI *api,
                         MatrixAPICallback callback,
                         gpointer user_data,
                         const gchar *user_id,
                         const gchar *room_id,
                         GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_room_tags(api, callback, user_data, user_id, room_id, error);
}

/**
 * matrix_api_delete_room_tag:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the id of the user to remove a tag for
 * @room_id: the id of the room to remove the tag from
 * @tag: the tag to remove
 * @error: return location for a #GError, or %NULL
 *
 * Remove a tag from the room.
 */
void
matrix_api_delete_room_tag(MatrixAPI *api,
                           MatrixAPICallback callback,
                           gpointer user_data,
                           const gchar *user_id,
                           const gchar *room_id,
                           const gchar *tag,
                           GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->delete_room_tag(api,
                          callback, user_data,
                          user_id, room_id, tag, error);
}

/**
 * matrix_api_add_room_tag:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @user_id: the ID of the user to add the tag for
 * @room_id: the ID of the room to add the tag for
 * @tag: the tag to add
 * @content: (transfer full): extra data for the tag, e.g. ordering
 * @error: return location for a #GError, or %NULL
 *
 * Add a tag to the room.
 */
void
matrix_api_add_room_tag(MatrixAPI *api,
                        MatrixAPICallback callback,
                        gpointer user_data,
                        const gchar *user_id,
                        const gchar *room_id,
                        const gchar *tag,
                        JsonNode *content,
                        GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->add_room_tag(api,
                       callback, user_data,
                       user_id, room_id, tag, content, error);
}

/* VoIP */

/**
 * matrix_api_get_turn_server:
 * @api: a #MatrixAPI implementation
 * @callback: (scope async): the function to call when the request is
 *            finished
 * @user_data: (closure): user data to pass to the callback function
 *             @callback
 * @error: return location for a #GError, or %NULL
 *
 * Get credentials for the client to use when initiating calls.
 */
void
matrix_api_get_turn_server(MatrixAPI *api,
                           MatrixAPICallback callback,
                           gpointer user_data,
                           GError **error)
{
    g_return_if_fail(MATRIX_IS_API(api));

    MATRIX_API_GET_IFACE(api)
        ->get_turn_server(api, callback, user_data, error);
}