/* * 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 * . */ #include "matrix-api.h" /** * SECTION:matrix-api * @short_description: Low level API interface * * The #MatrixAPI interface allows low-level communication with Matrix.org homeservers. */ /** * MatrixAPI: * * Base interface for low level Client/Server API functionality. */ /** * MatrixAPIInterface: * @abort_pending: the virtual function pointer to matrix_api_abort_pending() * @get_3pids: the virtual function pointer to matrix_api_get_3pids() * @add_3pid: the virtual function pointer to matrix_api_add_3pid() * @deactivate_account: the virtual function pointer to matrix_api_deactivate_account() * @change_password: the virtual function pointer to matrix_api_change_password() * @whoami: the virtual function pointer to matrix_api_whoami() * @get_profile: the virtual function pointer to matrix_api_get_profile() * @get_avatar_url: the virtual function pointer to matrix_api_get_avatar_url() * @set_avatar_url: the virtual function pointer to matrix_api_set_avatar_url() * @get_display_name: the virtual function pointer to matrix_api_get_display_name() * @set_display_name: the virtual function pointer to matrix_api_set_display_name() * @register_account: the virtual function pointer to matrix_api_register_account() * @register_account_email: the virtual function pointer to matrix_api_register_account_email() * @set_account_data: the virtual function pointer to matrix_api_set_account_data() * @get_room_tags: the virtual function pointer to matrix_api_get_room_tags() * @delete_room_tag: the virtual function pointer to matrix_api_delete_room_tag() * @add_room_tag: the virtual function pointer to matrix_api_add_room_tag() * @whois: the virtual function pointer to matrix_api_whois() * @versions: the virtual function pointer to matrix_api_versions() * @create_room: the virtual function pointer to matrix_api_create_room() * @delete_room_alias: the virtual function pointer to matrix_api_delete_room_alias() * @get_room_id: the virtual function pointer to matrix_api_get_room_id() * @create_room_alias: the virtual function pointer to matrix_api_create_room_alias() * @event_stream: the virtual function pointer to matrix_api_event_stream() * @get_event: the virtual function pointer to matrix_api_get_event() * @initial_sync: the virtual function pointer to matrix_api_initial_sync() * @get_event_context: the virtual function pointer to matrix_api_get_event_context() * @initial_sync_room: the virtual function pointer to matrix_api_initial_sync_room() * @list_room_members: the virtual function pointer to matrix_api_list_room_members() * @list_room_messages: the virtual function pointer to matrix_api_list_room_messages() * @send_event_receipt: the virtual function pointer to matrix_api_send_event_receipt() * @redact_event: the virtual function pointer to matrix_api_redact_event() * @send_event: the virtual function pointer to matrix_api_send_event() * @get_room_state: the virtual function pointer to matrix_api_get_room_state() * @send_state_event: the virtual function pointer to matrix_api_send_state_event() * @notify_room_typing: the virtual function pointer to matrix_api_notify_room_typing() * @sync: the virtual function pointer to matrix_api_sync() * @create_filter: the virtual function pointer to matrix_api_create_filter() * @download_filter: the virtual function pointer to matrix_api_download_filter() * @join_room_id_or_alias: the virtual function pointer to matrix_api_join_room_id_or_alias() * @ban_user: the virtual function pointer to matrix_api_ban_user() * @forget_room: the virtual function pointer to matrix_api_forget_room() * @invite_user_3rdparty: the virtual function pointer to matrix_api_invite_user_3rdparty() * @invite_user: the virtual function pointer to matrix_api_invite_user() * @join_room: the virtual function pointer to matrix_api_join_room() * @get_joined_rooms: the virtual function pointer to matrix_api_get_joined_rooms() * @kick_user: the virtual function pointer to matrix_api_kick_user() * @leave_room: the virtual function pointer to matrix_api_leave_room() * @unban_user: the virtual function pointer to matrix_api_unban_user() * @login: the virtual function pointer to matrix_api_login() * @logout: the virtual function pointer to matrix_api_logout() * @get_presence_list: the virtual function pointer to matrix_api_get_presence_list() * @update_presence_list: the virtual function pointer to matrix_api_update_presence_list() * @get_presence: the virtual function pointer to matrix_api_get_presence() * @set_presence: the virtual function pointer to matrix_api_set_presence() * @list_public_rooms: the virtual function pointer to matrix_api_list_public_rooms() * @get_pushers: the virtual function pointer to matrix_api_get_pushers() * @update_pusher: the virtual function pointer to matrix_api_update_pusher() * @get_notifications: the virtual function pointer to matrix_api_get_notifications() * @get_pushrules: the virtual function pointer to matrix_api_get_pushrules() * @delete_pushrule: the virtual function pointer to matrix_api_delete_pushrule() * @get_pushrule: the virtual function pointer to matrix_api_get_pushrule() * @add_pushrule: the virtual function pointer to matrix_api_add_pushrule() * @toggle_pushrule: the virtual function pointer to matrix_api_toggle_pushrule() * @search: the virtual function pointer to matrix_api_search() * @get_turn_server: the virtual function pointer to matrix_api_get_turn_server() * @media_download: the virtual function pointer to matrix_api_media_download() * @media_thumbnail: the virtual function pointer to matrix_api_media_thumbnail() * @media_upload: the virtual function pointer to matrix_api_media_upload() * @get_token: the virtual function pointer to matrix_api_get_token() * @set_token: the virtual function pointer to matrix_api_set_token() * @get_user_id: the virtual function pointer to matrix_api_get_user_id() * @set_user_id: the virtual function pointer to matrix_api_set_user_id() * @get_homeserver: the virtual function pointer to matrix_api_get_homeserver() * @set_homeserver: the virtual function pointer to matrix_api_set_homeserver() * * The virtual function table for for #MatrixAPI. */ G_DEFINE_INTERFACE(MatrixAPI, matrix_api, G_TYPE_OBJECT); /** * MATRIX_DEPRECATED_FOR: * @f: a function name * * Macro to notify compilers about deprecation, in favour of @f. */ /** * matrix_api_abort_pending: * @api: a #MatrixAPI * * Abort all pending requests toward a Matrix homeserver. Be aware that this may leave * requests in an inconsistent state. */ void matrix_api_abort_pending(MatrixAPI *matrix_api) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->abort_pending(matrix_api); } /** * matrix_api_get_3pids: * @api: a #MatrixAPI * @callback: (scope async): the callback function to call when the request is finished * @user_data: user data to pass to the callback function * @error: (nullable): a #GError, or %NULL to ignore errors * * 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 *matrix_api, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_3pids(matrix_api, callback, user_data, error); } /** * matrix_api_add_3pid: * @api: a #MatrixAPI * @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: (not nullable): the credentials to associate with the account * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Add contact information to the user’s account. */ void matrix_api_add_3pid(MatrixAPI *matrix_api, gboolean bind_creds, Matrix3PidCredential *threepid_creds, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(threepid_creds != NULL); MATRIX_API_GET_IFACE(matrix_api)->add_3pid(matrix_api, callback, user_data, bind_creds, threepid_creds, error); } /** * matrix_api_deactivate_account: * @api: a #MatrixAPI * @session: optional session token provided by the server * @login_type: the login type the client is trying to complete * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Deactivate the account. */ void matrix_api_deactivate_account(MatrixAPI *matrix_api, const gchar *session, const gchar *login_type, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->deactivate_account(matrix_api, callback, user_data, session, login_type, error); } /** * matrix_api_change_password: * @api: a #MatrixAPI * @new_password: (not nullable): the new password for the account * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Change the active user’s password. */ void matrix_api_change_password(MatrixAPI *matrix_api, const gchar *new_password, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(new_password != NULL); MATRIX_API_GET_IFACE(matrix_api)->change_password(matrix_api, callback, user_data, new_password, error); } /** * matrix_api_whoami: * @api: a #MatrixAPI * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get the user’s Matrix ID. */ void matrix_api_whoami(MatrixAPI *api, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(api != NULL); MATRIX_API_GET_IFACE(api)->whoami(api, callback, user_data, error); } /** * matrix_api_get_profile: * @api: a #MatrixAPI * @user_id: (not nullable): the user whose profile to get * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get a user’s profile. */ void matrix_api_get_profile(MatrixAPI *matrix_api, const gchar *user_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_profile(matrix_api, callback, user_data, user_id, error); } /** * matrix_api_get_avatar_url: * @api: a #MatrixAPI * @user_id: (not nullable): the user whose avatar URL to get * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get the URL of the specified user’s avatar. */ void matrix_api_get_avatar_url(MatrixAPI *matrix_api, const gchar *user_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_avatar_url(matrix_api, callback, user_data, user_id, error); } /** * matrix_api_set_avatar_url: * @api: a #MatrixAPI * @callback: (scope async): the function to call when the request is finished * @user_id: (not nullable): the user whose avatar URL to set * @avatar_url: the avatar URL info * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Set the user’s avatar URL. */ void matrix_api_set_avatar_url(MatrixAPI *matrix_api, const gchar *user_id, const gchar *avatar_url, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->set_avatar_url(matrix_api, callback, user_data, user_id, avatar_url, error); } /** * matrix_api_get_display_name: * @api: a #MatrixAPI * @user_id: (not nullable): the user whose display name to get * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get the user’s display name. */ void matrix_api_get_display_name(MatrixAPI *matrix_api, const gchar *user_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_display_name(matrix_api, callback, user_data, user_id, error); } /** * matrix_api_set_display_name: * @api: a #MatrixAPI * @user_id: (not nullable): the user whose display name to set * @display_name: the display name info * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Set the user’s display name. */ void matrix_api_set_display_name(MatrixAPI *matrix_api, const gchar *user_id, const gchar *display_name, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->set_display_name(matrix_api, callback, user_data, user_id, display_name, error); } /** * matrix_api_register_account: * @api: a #MatrixAPI * @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: the local part of the desired Matrix ID. If omitted, the server will generate a * local part * @password: (not nullable): the desired password for the account * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Attempt to register an account with the homeserver using @username and @password. * * Implementations of this method must set the #MatrixAPI:token property on a successful login. */ void matrix_api_register_account(MatrixAPI *matrix_api, MatrixAccountKind account_kind, gboolean bind_email, const gchar *username, const gchar *password, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(password != NULL); MATRIX_API_GET_IFACE(matrix_api)->register_account(matrix_api, callback, user_data, account_kind, bind_email, username, password, error); } /** * matrix_api_register_account_email: * @callback: (scope async): the function to call when the request is finished */ void matrix_api_register_account_email(MatrixAPI *api, const gchar *id_server, const gchar *client_secret, const gchar *email, guint send_attempt, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(api != NULL); g_return_if_fail(id_server); g_return_if_fail(client_secret); g_return_if_fail(email); MATRIX_API_GET_IFACE(api)->register_account_email(api, callback, user_data, id_server, client_secret, email, send_attempt, error); } /** * matrix_api_set_account_data: * @api: a #MatrixAPI * @user_id: (not nullable): 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: the room to set account data for. If %NULL, the account data will be set globally * @event_type: (not nullable): the event type of the account data to set. Custom types * should be namespaced to avoid clashes * @content: (not nullable): the content of the account data * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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 *matrix_api, const gchar *user_id, const gchar *room_id, const gchar *event_type, JsonNode *content, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); g_return_if_fail(event_type != NULL); g_return_if_fail(content != NULL); MATRIX_API_GET_IFACE(matrix_api)->set_account_data(matrix_api, callback, user_data, user_id, room_id, event_type, content, error); } /** * matrix_api_get_room_tags: * @api: a #MatrixAPI * @user_id: (not nullable): 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: (not nullable): the room to get tags for * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * List the tags set by a user on a room. */ void matrix_api_get_room_tags(MatrixAPI *matrix_api, const gchar *user_id, const gchar *room_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); g_return_if_fail(room_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_room_tags(matrix_api, callback, user_data, user_id, room_id, error); } /** * matrix_api_delete_room_tag: * @api: a #MatrixAPI * @user_id: (not nullable): the id of the user to remove a tag for * @room_id: (not nullable): the id of the room to remove the tag from * @tag: (not nullable): the tag to remove * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Remove a tag from the room. */ void matrix_api_delete_room_tag(MatrixAPI *matrix_api, const gchar *user_id, const gchar *room_id, const gchar *tag, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); g_return_if_fail(room_id != NULL); g_return_if_fail(tag != NULL); MATRIX_API_GET_IFACE(matrix_api)->delete_room_tag(matrix_api, callback, user_data, user_id, room_id, tag, error); } /** * matrix_api_add_room_tag: * @api: a #MatrixAPI * @user_id: (not nullable): the ID of the user to add the tag for * @room_id: (not nullable): the ID of the room to add the tag for * @tag: (not nullable): the tag to add * @content: extra data for the tag, e.g. ordering * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Add a tag to the room. */ void matrix_api_add_room_tag(MatrixAPI *matrix_api, const gchar *user_id, const gchar *room_id, const gchar *tag, JsonNode *content, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); g_return_if_fail(room_id != NULL); g_return_if_fail(tag != NULL); MATRIX_API_GET_IFACE(matrix_api)->add_room_tag(matrix_api, callback, user_data, user_id, room_id, tag, content, error); } /** * matrix_api_whois: * @api: a #MatrixAPI * @user_id: (not nullable): the user ID to look up * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get information about a particular user. */ void matrix_api_whois(MatrixAPI *matrix_api, const gchar *user_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->whois(matrix_api, callback, user_data, user_id, error); } /** * matrix_api_versions: * @api: a #MatrixAPI * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get the versions of the specification supported by the server. */ void matrix_api_versions(MatrixAPI *matrix_api, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->versions(matrix_api, callback, user_data, error); } /** * matrix_api_create_room: * @api: a #MatrixAPI * @preset: a room preset to use * @room_name: the desired display name for the room * @room_alias: an alias of the room * @topic: the topic of the room * @visibility: the initial visibility of the room * @creation_content: extra keys to be added to the content of m.room.create * @initial_state: a list of state events to set in the new room * @n_initial_state: the length of @initial_state * @invitees: list of user IDs to invite to the new room * @n_invitees: the length of @invitees * @invite_3pids: a list of 3rd party credentials to invite to the new room * @n_invite_3pids: the length of @invite_3pids * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Create a new room with the given name and invite the users in @invitees. */ void matrix_api_create_room(MatrixAPI *matrix_api, MatrixRoomPreset preset, const gchar *room_name, const gchar *room_alias, const gchar *topic, MatrixRoomVisibility visibility, JsonNode *creation_content, MatrixEventState **initial_state, int n_initial_state, gchar **invitees, int n_invitees, Matrix3PidCredential **invite_3pids, int n_invite_3pids, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->create_room(matrix_api, callback, user_data, preset, room_name, room_alias, topic, visibility, creation_content, initial_state, n_initial_state, invitees, n_invitees, invite_3pids, n_invite_3pids, error); } /** * matrix_api_delete_room_alias: * @api: a #MatrixAPI * @room_alias: (not nullable): the alias name to remove * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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 *matrix_api, const gchar *room_alias, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_alias != NULL); MATRIX_API_GET_IFACE(matrix_api)->delete_room_alias(matrix_api, callback, user_data, room_alias, error); } /** * matrix_api_get_joined_rooms: * @api: a #MatrixAPI * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get the rooms the current user is joined to. */ void matrix_api_get_joined_rooms(MatrixAPI *api, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(api != NULL); MATRIX_API_GET_IFACE(api)->get_joined_rooms(api, callback, user_data, error); } /** * matrix_api_get_room_id: * @api: a #MatrixAPI * @room_alias: (not nullable): the room alias * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get the room ID corresponding to this room alias. */ void matrix_api_get_room_id(MatrixAPI *matrix_api, const gchar *room_alias, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_alias != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_room_id(matrix_api, callback, user_data, room_alias, error); } /** * matrix_api_create_room_alias: * @api: a #MatrixAPI * @room_id: (not nullable): the room ID to add this alias to * @room_alias: (not nullable): the room alias to set * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Create a new mapping from room alias to room ID. */ void matrix_api_create_room_alias(MatrixAPI *matrix_api, const gchar *room_id, const gchar *room_alias, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); g_return_if_fail(room_alias != NULL); MATRIX_API_GET_IFACE(matrix_api)->create_room_alias(matrix_api, callback, user_data, room_id, room_alias, error); } /** * matrix_api_event_stream: * @api: a #MatrixAPI * @from_token: events will be listed from this token * @timeout: timeout of the request * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get the event stream, optionally beginning from @from_token. * * Deprecated: This functionality is deprecated on the Matrix specification level. * Use matrix_api_sync() instead. */ void matrix_api_event_stream(MatrixAPI *matrix_api, const gchar *from_token, gulong timeout, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->event_stream(matrix_api, callback, user_data, from_token, timeout, error); } /** * matrix_api_get_event: * @api: a #MatrixAPI * @event_id: (not nullable): the event ID to get * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get a single event by event ID. */ void matrix_api_get_event(MatrixAPI *matrix_api, const gchar *event_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(event_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_event(matrix_api, callback, user_data, event_id, error); } /** * matrix_api_initial_sync: * @api: a #MatrixAPI * @limit: the maximum number of events to get * @archived: whether to include rooms that the user has left * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Perform an initial sync of events. */ void matrix_api_initial_sync(MatrixAPI *matrix_api, guint limit, gboolean archived, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->initial_sync(matrix_api, callback, user_data, limit, archived, error); } /** * matrix_api_get_event_context: * @api: a #MatrixAPI * @room_id: (not nullable): the room to get events from * @event_id: (not nullable): 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) * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Gets a number of events that happened just before and after the specified event. */ void matrix_api_get_event_context(MatrixAPI *matrix_api, const gchar *room_id, const gchar *event_id, guint limit, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_event_context(matrix_api, callback, user_data, room_id, event_id, limit, error); } /** * matrix_api_initial_sync_room: * @api: a #MatrixAPI * @room_id: (not nullable): the room to get the data for * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get a copy of the current state and the most recent messages in a room. */ void matrix_api_initial_sync_room(MatrixAPI *matrix_api, const gchar *room_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->initial_sync_room(matrix_api, callback, user_data, room_id, error); } /** * matrix_api_list_room_members: * @api: a #MatrixAPI * @room_id: (not nullable): the room to get the member events for * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get the list of members for a room. */ void matrix_api_list_room_members(MatrixAPI *matrix_api, const gchar *room_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->list_room_members(matrix_api, callback, user_data, room_id, error); } /** * matrix_api_list_room_messages: * @api: a #MatrixAPI * @room_id: (not nullable): the room to get the events for * @from_token: (not nullable): 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 * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get a list of message and state events for a room. */ void matrix_api_list_room_messages(MatrixAPI *matrix_api, const gchar *room_id, const gchar *from_token, MatrixEventDirection direction, guint limit, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); g_return_if_fail(from_token != NULL); MATRIX_API_GET_IFACE(matrix_api)->list_room_messages(matrix_api, callback, user_data, room_id, from_token, direction, limit, error); } /** * matrix_api_send_event_receipt: * @api: a #MatrixAPI * @room_id: (not nullable): the room in which to send the event * @receipt_type: (not nullable): type of the receipt * @event_id: (not nullable): the event ID to acknowledge up to * @receipt: (not nullable): extra receipt information to attach. Note that the server will automatically * attach the `ta` field * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Update the marker for the given receipt type to the event ID specified. */ void matrix_api_send_event_receipt(MatrixAPI *matrix_api, const gchar *room_id, MatrixReceiptType receipt_type, const gchar *event_id, JsonNode *receipt, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); g_return_if_fail(event_id != NULL); g_return_if_fail(receipt_type != MATRIX_RECEIPT_TYPE_UNKNOWN); MATRIX_API_GET_IFACE(matrix_api)->send_event_receipt(matrix_api, callback, user_data, room_id, receipt_type, event_id, receipt, error); } /** * matrix_api_redact_event: * @api: a #MatrixAPI * @room_id: (not nullable): the room from which to redact the event * @event_id: (not nullable): the event ID to acknowledge up to * @txn_id: (not nullable): 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: the reason for the event being redacted * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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 * `redact` power level of the room may redact events there. */ void matrix_api_redact_event(MatrixAPI *matrix_api, const gchar *room_id, const gchar *event_id, const gchar *txn_id, const gchar *reason, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id); g_return_if_fail(event_id); g_return_if_fail(txn_id); MATRIX_API_GET_IFACE(matrix_api)->redact_event(matrix_api, callback, user_data, room_id, event_id, txn_id, reason, error); } /** * matrix_api_send_event: * @api: a #MatrixAPI * @callback: (scope async): the function to call when the request is finished * @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: the content of the event as a #JsonNode * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Send a message event to the room. */ void matrix_api_send_event(MatrixAPI *matrix_api, const gchar *room_id, const gchar *event_type, const gchar *txn_id, JsonNode *content, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id); g_return_if_fail(event_type); g_return_if_fail(txn_id); g_return_if_fail(content); MATRIX_API_GET_IFACE(matrix_api)->send_event(matrix_api, callback, user_data, room_id, event_type, txn_id, content, error); } /** * matrix_api_get_room_state: * @api: a #MatrixAPI * @room_id: (not nullable): the room ID to get a state for * @event_type: the type of state to look up * @state_key: the key of the state to look up. If @event_type is %NULL, this parameter is * ignored * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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. * * If @event_type is %NULL but @state_key is not %NULL, this function returns immediately and * @error is set to #MATRIX_ERROR_INCOMPLETE. */ void matrix_api_get_room_state(MatrixAPI *matrix_api, const gchar *room_id, const gchar *event_type, const gchar *state_key, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); if ((state_key != NULL) && (event_type == NULL)) { g_set_error(error, MATRIX_ERROR, MATRIX_ERROR_INCOMPLETE, "event_type must be set if state_key is set"); return; } MATRIX_API_GET_IFACE(matrix_api)->get_room_state(matrix_api, callback, user_data, room_id, event_type, state_key, error); } /** * matrix_api_send_state_event: * @api: a #MatrixAPI * @room_id: (not nullable): the room ID to get a state for * @event_type: the type of state to look up * @state_key: the key of the state to look up. If @event_type is %NULL, this parameter is ignored * @content: (not nullable): the content of the state event * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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. * * If @state_key is not %NULL but @event_type is %NULL, this function returns immediately, and * @error is set to #MATRIX_ERROR_INCOMPLETE. */ void matrix_api_send_state_event(MatrixAPI *matrix_api, const gchar *room_id, const gchar *event_type, const gchar *state_key, JsonNode *content, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); if ((room_id == NULL) || (content == NULL) || ((event_type == NULL) && (state_key != NULL))) { g_set_error(error, MATRIX_ERROR, MATRIX_ERROR_INCOMPLETE, "room_id and content must be set, and event_type cannot be NULL if state_key is not NULL"); return; } MATRIX_API_GET_IFACE(matrix_api)->send_state_event(matrix_api, callback, user_data, room_id, event_type, state_key, content, error); } /** * matrix_api_notify_room_typing: * @api: a #MatrixAPI * @user_id: (not nullable): the user who has started to type * @room_id: (not nullable): 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) * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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 *matrix_api, const gchar *user_id, const gchar *room_id, guint timeout, gboolean typing, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->notify_room_typing(matrix_api, callback, user_data, user_id, room_id, timeout, typing, error); } /** * matrix_api_sync: * @api: a #MatrixAPI * @filter_id: a filter ID created by the filter API (e.g. matrix_api_create_filter()) * @filter: a definition on what events to fetch * @since: 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 * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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. */ void matrix_api_sync(MatrixAPI *matrix_api, const gchar *filter_id, MatrixFilter *filter, const gchar *since, gboolean full_state, gboolean set_presence, gulong timeout, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->sync(matrix_api, callback, user_data, filter_id, filter, since, full_state, set_presence, timeout, error); } /** * matrix_api_create_filter: * @api: a #MatrixAPI * @user_id: (not nullable): 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: (not nullable): the filter to upload * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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 *matrix_api, const gchar *user_id, MatrixFilter *filter, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); g_return_if_fail(filter != NULL); MATRIX_API_GET_IFACE(matrix_api)->create_filter(matrix_api, callback, user_data, user_id, filter, error); } /** * matrix_api_download_filter: * @api: a #MatrixAPI * @user_id: (not nullable): the user ID to download a filter from * @filter_id: (not nullable): the filter ID to download * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Download a filter. */ void matrix_api_download_filter(MatrixAPI *matrix_api, const gchar *user_id, const gchar *filter_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); g_return_if_fail(filter_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->download_filter(matrix_api, callback, user_data, user_id, filter_id, error); } /** * matrix_api_join_room_id_or_alias: * @api: a #MatrixAPI * @callback: (scope async): the function to call when the reuest is finished * @room_id_or_alias: (not nullable): the ID or alias of a room to join * @user_data: user data to be passed to @callback * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Join a room by a room ID or an alias */ void matrix_api_join_room_id_or_alias(MatrixAPI *matrix_api, const gchar *room_id_or_alias, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id_or_alias != NULL); MATRIX_API_GET_IFACE(matrix_api)->join_room_id_or_alias(matrix_api, callback, user_data, room_id_or_alias, error); } /** * matrix_api_ban_user: * @api: a #MatrixAPI * @callback: (scope async): the function to call when the request is finished * @room_id: (not nullable): the room ID where the user should be banned * @user_id: (not nullable): the user ID to ban * @reason: the reason of the ban * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Ban the specified user from the specified room. An optional reason can be specified. */ void matrix_api_ban_user(MatrixAPI *matrix_api, const gchar *room_id, const gchar *user_id, const gchar *reason, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->ban_user(matrix_api, callback, user_data, room_id, user_id, reason, error); } /** * matrix_api_forget_room: * @api: a #MatrixAPI * @room_id: (not nullable): the room ID to forget * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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. */ void matrix_api_forget_room(MatrixAPI *matrix_api, const gchar *room_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->forget_room(matrix_api, callback, user_data, room_id, error); } /** * matrix_api_invite_user_3rdparty: * @api: a #MatrixAPI * @room_id: the room ID to which to invite the user * @credential: (not nullable): a {@link Matrix.3PidCredential} that identifies a user to invite * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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 *matrix_api, const gchar *room_id, Matrix3PidCredential *credential, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(credential != NULL); MATRIX_API_GET_IFACE(matrix_api)->invite_user_3rdparty(matrix_api, callback, user_data, room_id, credential, error); } /** * matrix_api_invite_user: * @api: a #MatrixAPI * @room_id: (not nullable): the room ID to invite the user to * @user_id: (not nullable): the user ID to invite * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Invite a user to a room. */ void matrix_api_invite_user(MatrixAPI *matrix_api, const gchar *room_id, const gchar *user_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->invite_user(matrix_api, callback, user_data, room_id, user_id, error); } /** * matrix_api_join_room: * @api: a #MatrixAPI * @room_id: (not nullable): the room ID to join to * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Join a room by its room ID. */ void matrix_api_join_room(MatrixAPI *matrix_api, const gchar *room_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->join_room(matrix_api, callback, user_data, room_id, error); } /** * matrix_api_kick_user: * @api: a #MatrixAPI * @room_id: (not nullable): the room ID to kick the user from * @user_id: the user ID to kick from the room * @reason: a reason * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Kick a user from a room */ void matrix_api_kick_user(MatrixAPI *matrix_api, const gchar *room_id, const gchar *user_id, const gchar *reason, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->kick_user(matrix_api, callback, user_data, room_id, user_id, reason, error); } /** * matrix_api_leave_room: * @api: a #MatrixAPI * @room_id: (not nullable): the room ID to kick the user from * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Leave a room. */ void matrix_api_leave_room(MatrixAPI *matrix_api, const gchar *room_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->leave_room(matrix_api, callback, user_data, room_id, error); } /** * matrix_api_unban_user: * @api: a #MatrixAPI * @room_id: (not nullable): the room ID to unban the user from * @user_id: the user ID to unban from the room * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Unban a user from a room */ void matrix_api_unban_user(MatrixAPI *matrix_api, const gchar *room_id, const gchar *user_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(room_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->unban_user(matrix_api, callback, user_data, room_id, user_id, error); } /** * matrix_api_login: * @api: a #MatrixAPI * @login_type: the login type to use * @content: parameters to pass for the login request * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Attempt to login with type @login_type. Implementations of this method must set the #MatrixAPI:token * property on a successful login. */ void matrix_api_login(MatrixAPI *matrix_api, const gchar *login_type, JsonNode *content, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(login_type != NULL); g_return_if_fail(content != NULL); MATRIX_API_GET_IFACE(matrix_api)->login(matrix_api, callback, user_data, login_type, content, error); } /** * matrix_api_logout: * @api: a #MatrixAPI * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Logout from the current session, invalidating the access token. */ void matrix_api_logout(MatrixAPI *matrix_api, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->logout(matrix_api, callback, user_data, error); } /** * matrix_api_get_presence_list: * @api: a #MatrixAPI * @user_id: (not nullable): the user whose presence list should be retrieved * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Retrieve a list of presence events for every user on this list. */ void matrix_api_get_presence_list(MatrixAPI *matrix_api, const gchar *user_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_presence_list(matrix_api, callback, user_data, user_id, error); } /** * matrix_api_update_presence_list: * @api: a #MatrixAPI * @user_id: (not nullable): the user whose presence list is being modified * @drop_ids: a list of user IDs to remove from the list * @n_drop_ids: the length of @drop_ids * @invite_ids: a list of user IDs to add to the list * @n_invite_ids: the length of @invite_ids * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Add or remove users from the specified user’s presence list. * * If both @drop_ids and @invite_ids are %NULL, this function returns immediately and @error * is set to #MATRIX_ERROR_INCOMPLETE. */ void matrix_api_update_presence_list(MatrixAPI *matrix_api, const gchar *user_id, gchar **drop_ids, int drop_ids_length1, gchar **invite_ids, int invite_ids_length1, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); if ((drop_ids == NULL) && (invite_ids == NULL)) { g_set_error(error, MATRIX_ERROR, MATRIX_ERROR_INCOMPLETE, "At least one of drop_ids and invite_ids must be set."); return; } MATRIX_API_GET_IFACE(matrix_api)->update_presence_list(matrix_api, callback, user_data, user_id, drop_ids, drop_ids_length1, invite_ids, invite_ids_length1, error); } /** * matrix_api_get_presence: * @api: a #MatrixAPI * @user_id: (not nullable): the user whose presence list is being modified * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get the given user’s presence state. */ void matrix_api_get_presence(MatrixAPI *matrix_api, const gchar *user_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_presence(matrix_api, callback, user_data, user_id, error); } /** * matrix_api_set_presence: * @api: a #MatrixAPI * @user_id: (not nullable): the user whose presence list is being modified * @presence: the new presence state * @status_message: a status message attached to this state * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Set the given user’s presence. You cannot set the presence of another user. */ void matrix_api_set_presence(MatrixAPI *matrix_api, const gchar *user_id, MatrixPresence presence, const gchar *status_message, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(user_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->set_presence(matrix_api, callback, user_data, user_id, presence, status_message, error); } /** * matrix_api_list_public_rooms: * @api: a #MatrixAPI * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * List the public rooms on the server. */ void matrix_api_list_public_rooms(MatrixAPI *matrix_api, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->list_public_rooms(matrix_api, callback, user_data, error); } /** * matrix_api_get_pushers: * @api: a #MatrixAPI * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Retrieve all push rulesets. */ void matrix_api_get_pushers(MatrixAPI *matrix_api, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_pushers(matrix_api, callback, user_data, error); } /** * matrix_api_update_pusher: * @api: a #MatrixAPI * @pusher: (not nullable): a #MatrixPusher * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Create, update or delete a pusher for the active user on this homeserver. */ void matrix_api_update_pusher(MatrixAPI *matrix_api, MatrixPusher *pusher, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->update_pusher(matrix_api, callback, user_data, pusher, error); } /** * matrix_api_get_notifications: * @api: a #MatrixAPI * @from_token: (nullable): Pagination token to retrieve the next set of events * @limit: Limit on the number of events to return in the request. Set to 0 for no limit * @filter: (nullable): Allows basic filtering of the events returned. Set it to `"highlight"` to * return only events where the notification had the highlight tweak set. * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get notifications from the server. */ void matrix_api_get_notifications(MatrixAPI *api, const gchar *from_token, guint limit, const gchar *filter, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(api != NULL); MATRIX_API_GET_IFACE(api)->get_notifications(api, from_token, limit, filter, callback, user_data, error); } /** * matrix_api_get_pushrules: * @api: a #MatrixAPI * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Retrieve all push rulesets. */ void matrix_api_get_pushrules(MatrixAPI *matrix_api, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_pushrules(matrix_api, callback, user_data, error); } /** * matrix_api_delete_pushrule: * @api: a #MatrixAPI * @scope: (not nullable): either `global` to specify global rules, or * `device/<profile tag>` for rules for a given `profile tag` * @kind: the kind of rule * @rule_id: (not nullable): an identifier for the rule * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Delete a push rule. */ void matrix_api_delete_pushrule(MatrixAPI *matrix_api, const gchar *scope, MatrixPusherKind kind, const gchar *rule_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(scope != NULL); g_return_if_fail(rule_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->delete_pushrule(matrix_api, callback, user_data, scope, kind, rule_id, error); } /** * matrix_api_get_pushrule: * @api: a #MatrixAPI * @scope: (not nullable): either `global` to specify global rules, or * `device/<profile tag>` for rules for a given `profile tag`. * @kind: the kind of rule * @rule_id: (not nullable): an identifier for the rule * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Retrieve a specific push rule. */ void matrix_api_get_pushrule(MatrixAPI *matrix_api, const gchar *scope, MatrixPusherKind kind, const gchar *rule_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(scope != NULL); g_return_if_fail(rule_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_pushrule(matrix_api, callback, user_data, scope, kind, rule_id, error); } /** * matrix_api_add_pushrule: * @api: a #MatrixAPI * @scope: (not nullable): either `global` to specify global rules, or * `device/<profile tag>` for rules for a given `profile tag` * @kind: the kind of rule * @rule_id: (not nullable): an identifier for the rule * @before: make the new rule the next-most important than this rule ID * @after: make the new rule the next-less important than this rule ID * @actions: (not nullable): the actions to perform when the conditions for this rule are met * @n_actions: the length of @actions * @conditions: the conditions that must hold true for an event for a rule to be applied. * A rule with no conditions always matches * @n_conditions: the length of @conditions * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Add or change a push rule. */ void matrix_api_add_pushrule(MatrixAPI *matrix_api, const gchar *scope, MatrixPusherKind kind, const gchar *rule_id, const gchar *before, const gchar *after, gchar **actions, int actions_length1, MatrixPusherConditionKind *conditions, int conditions_length1, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(scope != NULL); g_return_if_fail(rule_id != NULL); g_return_if_fail(actions != NULL); MATRIX_API_GET_IFACE(matrix_api)->add_pushrule(matrix_api, callback, user_data, scope, kind, rule_id, before, after, actions, actions_length1, conditions, conditions_length1, error); } /** * matrix_api_toggle_pushrule: * @api: a #MatrixAPI * @scope: (not nullable): either `global` to specify global rules, or * `device/<profile tag>` for rules for a given `profile tag` * @kind: the kind of rule * @rule_id: (not nullable): an identifier for the rule * @enabled: if %TRUE, the rule will be enabled, otherwise it gets disabled * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Enable or disable the specified push rule. */ void matrix_api_toggle_pushrule(MatrixAPI *matrix_api, const gchar *scope, MatrixPusherKind kind, const gchar *rule_id, gboolean enabled, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(scope != NULL); g_return_if_fail(rule_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->toggle_pushrule(matrix_api, callback, user_data, scope, kind, rule_id, enabled, error); } /** * matrix_api_search: * @api: a #MatrixAPI * @next_batch: the point to return events from. If given, this should be a next_batch result * from a previous call to this method * @search_categories: describes which categories to search, and their criteria * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Perform a server side search. */ void matrix_api_search(MatrixAPI *matrix_api, const gchar *next_batch, MatrixSearchCategories *search_categories, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->search(matrix_api, callback, user_data, next_batch, search_categories, error); } /** * matrix_api_get_turn_server: * @api: a #MatrixAPI * @callback: (scope async): the function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Get credentials for the client to use when initiating calls. */ void matrix_api_get_turn_server(MatrixAPI *matrix_api, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->get_turn_server(matrix_api, callback, user_data, error); } /** * matrix_api_media_download: * @api: a #MatrixAPI * @server_name: (not nullable): the server name from the `mxc:` URI * @media_id: (not nullable): the media ID from the `mxc:` URI * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Download content from the content repository. */ void matrix_api_media_download(MatrixAPI *matrix_api, const gchar *server_name, const gchar *media_id, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(server_name != NULL); g_return_if_fail(media_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->media_download(matrix_api, callback, user_data, server_name, media_id, error); } /** * matrix_api_media_thumbnail: * @api: a #MatrixAPI * @server_name: (not nullable): the server name from the `mxc:` URI * @media_id: (not nullable): the media ID from the `mxc:` URI * @width: the width of the media, in pixels * @height: the height of the media, in pixels * @method: the resize method to use * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * 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 *matrix_api, const gchar *server_name, const gchar *media_id, guint width, guint height, MatrixResizeMethod method, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(server_name != NULL); g_return_if_fail(media_id != NULL); MATRIX_API_GET_IFACE(matrix_api)->media_thumbnail(matrix_api, callback, user_data, server_name, media_id, width, height, method, error); } /** * matrix_api_media_upload: * @api: a #MatrixAPI * @content_type: the type of the content to be uploaded * @content: (not nullable): the content to be uploaded * @callback: (scope async): a function to call when the request is finished * @user_data: user data to be passed to @callback * @error: (nullable): a #GError, or %NULL to ignore errors * * Upload some content to the content repository. */ void matrix_api_media_upload(MatrixAPI *matrix_api, const gchar *content_type, GByteArray *content, MatrixAPICallback callback, gpointer user_data, GError **error) { g_return_if_fail(matrix_api != NULL); g_return_if_fail(content != NULL); MATRIX_API_GET_IFACE(matrix_api)->media_upload(matrix_api, callback, user_data, content_type, content, error); } /** * matrix_api_get_token: * @api: a #MatrixAPI * * Get the access token used in @api. * * The returned value is owned by @api and should not be freed. * * Returns: (transfer none) (nullable): an access token, or %NULL if not yet set */ const gchar * matrix_api_get_token(MatrixAPI *matrix_api) { g_return_val_if_fail(matrix_api != NULL, NULL); return MATRIX_API_GET_IFACE(matrix_api)->get_token(matrix_api); } /** * matrix_api_set_token: * @api: a #MatrixAPI * @token: (transfer none): an access token * * Set the access token to be used for authorization while using @api. */ void matrix_api_set_token(MatrixAPI *matrix_api, const gchar *value) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->set_token(matrix_api, value); } /** * matrix_api_get_user_id: * @api: a #MatrixAPI * * Get the user ID of the user logged in using @api. * * The returned value is owned by @api and should not be freed. * * Returns: (transfer none) (nullable): a Matrix ID, or %NULL if not yet set */ const gchar * matrix_api_get_user_id(MatrixAPI *matrix_api) { g_return_val_if_fail(matrix_api != NULL, NULL); return MATRIX_API_GET_IFACE(matrix_api)->get_user_id(matrix_api); } /** * matrix_api_set_user_id: * @api: a #MatrixAPI * @user_id: (nullable): a Matrix ID * * Set the user ID of the user logged in using @api. This might be useful for restoring state. */ void matrix_api_set_user_id(MatrixAPI *matrix_api, const gchar *user_id) { g_return_if_fail(matrix_api != NULL); MATRIX_API_GET_IFACE(matrix_api)->set_user_id(matrix_api, user_id); } /** * matrix_api_get_homeserver: * @api: a #MatrixAPI * * Get the name of the homeserver, as it calls itself. * * The returned value is owned by @api and should not be freed. * * Returns: (transfer none) (nullable): a homeserver name */ const gchar * matrix_api_get_homeserver(MatrixAPI *matrix_api) { g_return_val_if_fail(matrix_api != NULL, NULL); return MATRIX_API_GET_IFACE(matrix_api)->get_homeserver(matrix_api); } /** * matrix_api_set_homeserver: * @api: a #MatrixAPI * @homeserver: (nullable): a homeserver name * * Set the name of the homeserver, as it calls itself. This might be useful for * restoring state. */ void matrix_api_set_homeserver(MatrixAPI *api, const gchar *homeserver) { g_return_if_fail(api != NULL); MATRIX_API_GET_IFACE(api)->set_homeserver(api, homeserver); } static void matrix_api_default_init(MatrixAPIInterface *iface) { static gboolean initialized = FALSE; if(!initialized) { initialized = TRUE; /** * 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", "token", "token", NULL, G_PARAM_STATIC_STRINGS | G_PARAM_READWRITE)); /** * MatrixAPI:user-id: * * The Matrix user ID that is currently authenticated with the server. It is set * automatically by the registration and login process. */ g_object_interface_install_property(iface, g_param_spec_string( "user-id", "user-id", "user-id", NULL, G_PARAM_STATIC_STRINGS | G_PARAM_READABLE)); /** * MatrixAPI:homeserver: * * The name of the Matrix home server as it calls itmatrix_api. It is set * automatically by the registration and login process. */ g_object_interface_install_property(iface, g_param_spec_string( "homeserver", "homeserver", "homeserver", NULL, G_PARAM_STATIC_STRINGS | G_PARAM_READABLE)); } }