matrix-api.h

/**
 * matrix-api.h: Interface to the matrix client/server API.
 *
 * The intention is that this module provides an interface to the matrix API
 * without anything purple-specific.
 *
 * Each API method takes a 'MatrixConnectionData *'; this is used to determine
 * the URL of the homeserver, and the access_token which is used for
 * authorisation.
 *
 * The methods are asynchronous, and take a callback to be called when the
 * request completes.
 *
 * The methods may return NULL in the case of configuration errors, in which
 * case the 'error_callback' will have been called *before* the method returns
 * - so you should be careful not to access data structures which that callback
 * frees.
 *
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111-1301 USA
 */

#ifndef MATRIX_API_H
#define MATRIX_API_H

/* libpurple */
#include "util.h"

#include "matrix-connection.h"

struct _JsonNode;
struct _JsonObject;

typedef struct _MatrixApiRequestData MatrixApiRequestData;

/**
 * This is the signature used for functions that act as the callback
 * to the matrix api methods
 *
 * @param conn          The MatrixConnectionData passed into the api method
 * @param user_data     The user data that your code passed into the api
 *                      method.
 * @param json_root     NULL if there was no body, or it could not be
 *                          parsed as JSON; otherwise the root of the JSON
 *                          tree in the response
 * @param body          NULL if the body was parsable as JSON, else the raw
 *                          body.
 * @param body_len      The length of the body (valid when body is)
 *
 * @param content_type  The content type of the body
 */
typedef void (*MatrixApiCallback)(MatrixConnectionData *conn,
                                  gpointer user_data,
                                  struct _JsonNode *json_root,
                                  const char *body,
                                  size_t body_len, const char *content_type);

/**
 * Signature for functions which are called when there is an error calling the
 * API (such as a connection failure)
 *
 * @param conn             The MatrixConnectionData passed into the api method
 * @param user_data        The user data that your code passed into the api
 *                             method.
 * @param error_message    a descriptive error message
 *
 */
typedef void (*MatrixApiErrorCallback)(MatrixConnectionData *conn,
        gpointer user_data, const gchar *error_message);

/**
 * Default error callback. We just put the connection into the "error" state.
 */
void matrix_api_error(MatrixConnectionData *conn, gpointer user_data,
        const gchar *error_message);

/**
 * Signature for functions which are called when the API returns a non-200
 * response.
 *
 * @param conn            The MatrixConnectionData passed into the api method
 * @param user_data       The user data that your code passed into the api
 *                            method.
 * @param http_response   HTTP response code.
 * @param json_root       NULL if there was no body, or it could not be
 *                            parsed as JSON; otherwise the root of the JSON
 *                            tree in the response
 */
typedef void (*MatrixApiBadResponseCallback)(MatrixConnectionData *conn,
        gpointer user_data, int http_response_code,
        struct _JsonNode *json_root);

/**
 * Default bad-response callback. We just put the connection into the "error"
 * state.
 */
void matrix_api_bad_response(MatrixConnectionData *ma, gpointer user_data,
        int http_response_code, struct _JsonNode *json_root);





/**
 * Cancel a call to an API. This will also call the error_callback
 * with an error message of "cancelled".
 *
 * @param request   The result from an earlier matrix_api_* call
 */
void matrix_api_cancel(MatrixApiRequestData *request);


/**
 * call the /login API
 *
 * @param conn       The connection with which to make the request
 * @param username   user id to pass in request
 * @param password   password to pass in request
 * @param callback   Function to be called when the request completes
 * @param user_data  Opaque data to be passed to the callback
 */
MatrixApiRequestData *matrix_api_password_login(MatrixConnectionData *conn,
        const gchar *username,
        const gchar *password,
        const gchar *device_id,
        MatrixApiCallback callback,
        gpointer user_data);


/**
 * call the /sync API
 *
 * @param conn       The connection with which to make the request
 * @param since      If non-null, the batch token to start sync from
 * @param timeout    Number of milliseconds after which the API will time out if
 *                      no events
 * @param full_state       If true, will do a full state sync instead of an
 *                             incremental sync
 * @param callback         Function to be called when the request completes
 * @param error_callback   Function to be called if there is an error making
 *                             the request. If NULL, matrix_api_error will be
 *                             used.
 * @param bad_response_callback Function to be called if the API gives a non-200
 *                            response. If NULL, matrix_api_bad_response will be
 *                            used.
 * @param user_data  Opaque data to be passed to the callback
 */
MatrixApiRequestData *matrix_api_sync(MatrixConnectionData *conn,
        const gchar *since, int timeout, gboolean full_state,
        MatrixApiCallback callback,
        MatrixApiErrorCallback error_callback,
        MatrixApiBadResponseCallback bad_response_callback,
        gpointer user_data);


/**
 * Send an event to a room
 *
 * @param conn       The connection with which to make the request
 * @param room_id          The room to send the event to
 * @param event_type       The type of event (eg "m.room.message")
 * @param txn_id           Unique transaction id
 * @param content          The content of the event
 * @param callback         Function to be called when the request completes
 * @param error_callback   Function to be called if there is an error making
 *                             the request. If NULL, matrix_api_error will be
 *                             used.
 * @param bad_response_callback Function to be called if the API gives a non-200
 *                            response. If NULL, matrix_api_bad_response will be
 *                            used.
 * @param user_data        Opaque data to be passed to the callbacks
 */
MatrixApiRequestData *matrix_api_send(MatrixConnectionData *conn,
        const gchar *room_id, const gchar *event_type, const gchar *txn_id,
        struct _JsonObject *content,
        MatrixApiCallback callback,
        MatrixApiErrorCallback error_callback,
        MatrixApiBadResponseCallback bad_response_callback,
        gpointer user_data);

/**
 * Invite a user to a room
 *
 * @param conn             The connection with which to make the request
 * @param room_id          The room id to invite the user to
 *
 * @param who              The mxid of the person to invite
 *
 * @param callback         Function to be called when the request completes
 * @param error_callback   Function to be called if there is an error making
 *                             the request. If NULL, matrix_api_error will be
 *                             used.
 * @param bad_response_callback Function to be called if the API gives a non-200
 *                            response. If NULL, matrix_api_bad_response will be
 *                            used.
 * @param user_data        Opaque data to be passed to the callbacks
 */
void matrix_api_invite_user(MatrixConnectionData *conn,
        const gchar *room_id,
        const gchar *who,
        MatrixApiCallback callback,
        MatrixApiErrorCallback error_callback,
        MatrixApiBadResponseCallback bad_response_callback,
        gpointer user_data);

/**
 * Make a request to join a room
 *
 * @param conn             The connection with which to make the request
 * @param room             The room (id or alias) to join
 * @param callback         Function to be called when the request completes
 * @param error_callback   Function to be called if there is an error making
 *                             the request. If NULL, matrix_api_error will be
 *                             used.
 * @param bad_response_callback Function to be called if the API gives a non-200
 *                            response. If NULL, matrix_api_bad_response will be
 *                            used.
 * @param user_data        Opaque data to be passed to the callbacks
 */
MatrixApiRequestData *matrix_api_join_room(MatrixConnectionData *conn,
        const gchar *room,
        MatrixApiCallback callback,
        MatrixApiErrorCallback error_callback,
        MatrixApiBadResponseCallback bad_response_callback,
        gpointer user_data);

/**
 * Sends a typing notifiaction to a room
 *
 * @param conn             The connection with which to make the request
 * @param room_id          The room id to send the typing notification to
 * @param typing           Whether to mark the user as typing
 * @param typing_timeout   How long the server should mark the user as typing
 * @param callback         Function to be called when the request completes
 * @param error_callback   Function to be called if there is an error making
 *                             the request. If NULL, matrix_api_error will be
 *                             used.
 * @param bad_response_callback Function to be called if the API gives a non-200
 *                            response. If NULL, matrix_api_bad_response will be
 *                            used.
 * @param user_data        Opaque data to be passed to the callbacks
 */
MatrixApiRequestData *matrix_api_typing(MatrixConnectionData *conn,
        const gchar *room_id, gboolean typing,
        gint typing_timeout, MatrixApiCallback callback,
        MatrixApiErrorCallback error_callback,
        MatrixApiBadResponseCallback bad_response_callback,
        gpointer user_data);


/**
 * Leave a room
 *
 * @param conn             The connection with which to make the request
 * @param room_id          The id of the room to leave
 * @param callback         Function to be called when the request completes
 * @param error_callback   Function to be called if there is an error making
 *                             the request. If NULL, matrix_api_error will be
 *                             used.
 * @param bad_response_callback Function to be called if the API gives a non-200
 *                            response. If NULL, matrix_api_bad_response will be
 *                            used.
 * @param user_data        Opaque data to be passed to the callbacks
 */
MatrixApiRequestData *matrix_api_leave_room(MatrixConnectionData *conn,
        const gchar *room_id,
        MatrixApiCallback callback,
        MatrixApiErrorCallback error_callback,
        MatrixApiBadResponseCallback bad_response_callback,
        gpointer user_data);


/**
 * Upload a file
 *
 * @param conn             The connection with which to make the request
 * @param ctype            Content type of file
 * @param data             Raw data content of file
 * @param data_len         Length of the data
 * @param callback         Function to be called when the request completes
 * @param user_data        Opaque data to be passed to the callback
 */
MatrixApiRequestData *matrix_api_upload_file(MatrixConnectionData *conn,
        const gchar *ctype,
        const gchar *data,
        gsize data_len,
        MatrixApiCallback callback,
        MatrixApiErrorCallback error_callback,
        MatrixApiBadResponseCallback bad_response_callback,
        gpointer user_data);


/* Get the complete download url for a given uri
 *
 * @param homeserver        The server hosting the file
 * @param uri               The file uri
 */
GString *get_download_url(const gchar *homeserver, const gchar *uri);


/**
 * Download a file
 *
 * @param conn             The connection with which to make the request
 * @param uri              The Matrix uri to fetch starting mxc://
 * @param max_size         A maximum size of file to receive.
 * @param callback         Function to be called when the request completes
 * @param error_callback   Function to be called if there is an error making
 *                             the request. If NULL, matrix_api_error will be
 *                             used.
 * @param bad_response_callback Function to be called if the API gives a non-200
 *                            response. If NULL, matrix_api_bad_response will be
 *                            used.
 * @param user_data        Opaque data to be passed to the callbacks
 *
 */
MatrixApiRequestData *matrix_api_download_file(MatrixConnectionData *conn,
        const gchar *uri,
        gsize max_size,
        MatrixApiCallback callback,
        MatrixApiErrorCallback error_callback,
        MatrixApiBadResponseCallback bad_response_callback,
        gpointer user_data);

/**
 * Download a thumbnail for a file
 *
 * @param conn             The connection with which to make the request
 * @param uri              The Matrix uri to fetch starting mxc://
 * @param max_size         A maximum size of file to receive.
 * @param width            Desired width; the server might not obey
 * @param height           Desired height; the server might not obey
 * @param scale            True to scale, false to crop
 * @param callback         Function to be called when the request completes
 * @param error_callback   Function to be called if there is an error making
 *                             the request. If NULL, matrix_api_error will be
 *                             used.
 * @param bad_response_callback Function to be called if the API gives a non-200
 *                            response. If NULL, matrix_api_bad_response will be
 *                            used.
 * @param user_data        Opaque data to be passed to the callbacks
 *
 */
MatrixApiRequestData *matrix_api_download_thumb(MatrixConnectionData *conn,
        const gchar *uri,
        gsize max_size,
        unsigned int width, unsigned int height, gboolean scale,
        MatrixApiCallback callback,
        MatrixApiErrorCallback error_callback,
        MatrixApiBadResponseCallback bad_response_callback,
        gpointer user_data);

/**
 * e2e: Upload keys; one or more of the device keys and the one time keys
 * @param conn             The connection with which to make the request
 * @param device_keys      (optional) Json Object with the signed device keys
 *                         device_keys gets unreferenced
 * @param one_time_keys    (optional) Json Object with one time key set
 *                         one_time_keys gets unreferenced
 * @param callback         Function to be called when the request completes
 * @param error_callback   Function to be called if there is an error making
 *                             the request. If NULL, matrix_api_error will be
 *                             used.
 * @param bad_response_callback Function to be called if the API gives a non-200
 *                            response. If NULL, matrix_api_bad_response will be
 *                            used.
 * @param user_data        Opaque data to be passed to the callbacks
 *
 */
MatrixApiRequestData *matrix_api_upload_keys(MatrixConnectionData *conn,
        struct _JsonObject *device_keys, struct _JsonObject *one_time_keys,
        MatrixApiCallback callback,
        MatrixApiErrorCallback error_callback,
        MatrixApiBadResponseCallback bad_response_callback,
        gpointer user_data);

#if 0
/**
 * Get the current state of a room
 *
 * @param conn             The connection with which to make the request
 * @param room_id          The room to get state for
 * @param callback         Function to be called when the request completes
 * @param user_data        Opaque data to be passed to the callbacks
 */
MatrixApiRequestData *matrix_api_get_room_state(MatrixConnectionData *conn,
        const gchar *room_id,
        MatrixApiCallback callback,
        gpointer user_data);
#endif

#endif