/* * 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 * . */ /** * Base interface for client communication with a Matrix.org * homeserver */ public interface Matrix.Client : GLib.Object { /** * This signal is a sign for a finished login request. * * Implementations are responsible for emitting this signal when * they get a response for a login request. * * @param success if %TRUE, login was successful */ public virtual signal void login_finished(bool success) {} /** * This signal is a sign of an incoming event. It gets emitted for * every signal, regardless if it is handled by other event * signals, before other signals. * * Implementations are responsible for emitting this signal when * any kind of event arrives from the event stream or the history. * * @param room_id the ID of the room associated with this event * @param raw_event the raw event as a JSON object * @param matrix_event the event as a {@link Matrix.Event} */ [Signal (detailed=true)] public virtual signal void @event(string? room_id, Json.Node raw_event, Matrix.Event.Base? matrix_event) {} /** * This signal is emitted when polling is started. */ public signal void polling_started(); /** * This signal gets invoked when polling is stopped due to any * reason. * * @param error gets set to an actual error if polling is stopped * due to one */ public signal void polling_stopped(GLib.Error? error); /** * Callback function delegate for the event signal. * * @param room_id the room the event associated with * @param raw_event the event as a raw JSON object * @param matrix_event the event as a Matrix.Event object */ public delegate void EventCallback(Matrix.Client client, string? room_id, Json.Node raw_event, Matrix.Event.Base? matrix_event); /** * Authenticate with the Matrix.org server with a username and * password. * * @param username the username to login with * @param password the password to use */ public abstract void login_with_password(string username, string password) throws Matrix.Error; /** * Register @username with the homeserver as a normal user. * * Upon success, the user is registered and authenticated. * * Implementations must emit the login-finished signal when a * response arrives. * * This method registers a normal user account. If you want to * register a different kind of user, use * matrix_api_register_account(). * * @param username the username to register. If omitted, the * server will generate one * @param password the password to use with the registration */ public abstract void register_with_password(string? username, string password) throws Matrix.Error; /** * Logout from the homeserver. As Matrix.org doesn’t have such a * concept, this cancels all ongoing requests and clears the * authentication data (e.g. tokens). */ public abstract void logout() throws Matrix.Error; /** * Begin polling the event stream. */ public abstract void begin_polling() throws Matrix.Error; /** * Stop polling the event stream. If @param cancel_ongoing is * {{{true}}}, ongoing requests will be cancelled, too. * * @param cancel_ongoing if {{{true}}}, ongoing requests will be * cancelled, too */ public abstract void stop_polling(bool cancel_ongoing) throws Matrix.Error; /** * Convenience function to emits the login-finished signal. * * @param success set to {{{true}}} if login was successful */ public void emit_login_finished(bool success) { login_finished(success); } /** * Emits the #MatrixClient::event signal. * * @param room_id the room this event is associated with * @param raw_event the raw event * @param matrix_event the event as a Matrix.Event */ public void incoming_event(string? room_id, Json.Node raw_event, Matrix.Event.Base? matrix_event) { Quark equark; if (matrix_event == null) { equark = typeof(Matrix.Event.Base).qname(); } else { equark = matrix_event.get_type().qname(); } this.@event[equark.to_string()](room_id, raw_event, matrix_event); } /** * Connect a handler for events. If @param event_gtype is * Matrix.Event, all events will be sent to the callback function, * otherwise only events that match the specified event type. * * If @event_gtype is not derived from * {@link Matrix.Event}, @param callback won’t get connected. * * @param event_gtype the {@link GLib.Type} of a * {@link Matrix.Event} derivative * @param event_callback the allback function to connect */ public extern void connect_event(GLib.Type event_gtype, owned EventCallback event_callback); /** * Get the profile of a user specified by @param user_id. * If @param room_id is not null, return the room-specific * profile. If the user's profile is not cached yet, * Matrix.Error.UNAVAILABLE is thrown. */ public abstract Profile? get_user_profile(string user_id, string? room_id = null) throws Matrix.Error; /** * Get the presence state of a user specified * by @param user_id. If @param room_id is null, return * the room specific presence state. If the user's presence * state is not cached yet, Matrix.Error.UNAVAILABLE is * thrown. */ public abstract Presence get_user_presence(string user_id, string? room_id = null) throws Matrix.Error; /** * Get a room object by the room ID specified in @param room_id. * If room data is not cached yet, Matrix.Error.UNAVAILABLE is * thrown. * * @param room_id the ID of a room * @return a Matrix.Room object */ public abstract Room get_room_by_id(string room_id) throws Matrix.Error; /** * Get a room object by the room alias specified * in @param room_alias. If room data is not cached yet, * {@link Matrix.Error.UNAVAILABLE} is thrown. * * @param room_alias a room alias * @return a Matrix.Room object */ public abstract Room get_room_by_alias(string room_alias) throws Matrix.Error; /** * Callback type for {@link Matrix.Client.send}. * * @param event_id the event_id returned by the server * @param err an error raised during event sending, if any */ public delegate void SendCallback(string? event_id, GLib.Error? err); /** * Send an event to the given room. This will use the * /room/{roomId}/send or /room/{roomId}/state API depending on * the event: if the event has a state key (there is a state_key * key in the generated JSON), even if an empty one, it will use * the latter. * * @param room_id the room to send the event to * @param evt the event to send * @param cb the callback function to call when the request is * finished * @param txn_id the transaction ID used by this request. In case * of a state event, it will be untouched */ public abstract void send(string room_id, Matrix.Event.Base evt, SendCallback? cb, out ulong txn_id) throws Matrix.Error; /* * Save the state of the client. Implementors can choose what they * actually save, and in what format. * * @param filename the name of the file to save state to */ public abstract void save_state(string filename) throws Matrix.Error, GLib.Error; /** * Load the state of the client, as saved by save_state(). * * @param filename the name of the file to load state from */ public abstract void load_state(string filename) throws Matrix.Error, GLib.Error; }