matrix-glib-sdk/src/matrix-api.c

2140 lines
74 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

/*
* This file is part of matrix-glib-sdk
*
* matrix-glib-sdk is free software: you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation, either
* version 3 of the License, or (at your option) any later version.
*
* matrix-glib-sdk is distributed in the hope that it will be
* useful, but WITHOUT ANY WARRANTY; without even the implied
* warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
* See the GNU Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with matrix-glib-sdk. If not, see
* <http://www.gnu.org/licenses/>.
*/
#include "matrix-api.h"
/**
* SECTION:matrix-api
* @title: MatrixAPI
* @short_description: An interface for actual API implementations,
* like #MatrixHTTPAPI
*
* This interface provides a skeleton for all API functionality for
* client communication with a Matrix.org homeserver.
**/
/**
* MatrixAPI:
*
* An opaque pointer type.
**/
/**
* MatrixAPIInterface:
* @get_token: virtual function for matrix_api_get_token()
* @set_token: virtual function for matrix_api_set_token()
* @get_refresh_token: virtual function for matrix_api_get_refresh_token()
* @set_refresh_token: virtual function for matrix_api_set_refresh_token()
* @get_user_id: virtual function for matrix_api_get_user_id()
* @get_homeserver: virtual function for matrix_api_get_homeserver()
* @media_download: virtual function for matrix_api_media_download()
* @media_thumbnail: virtual function for matrix_api_media_thumbnail()
* @media_upload: virtual function for matrix_api_media_upload()
* @get_presence_list: virtual function for matrix_api_get_presence_list()
* @update_presence_list: virtual function for matrix_api_update_presence_list()
* @get_user_presence: virtual function for matrix_api_get_user_presence()
* @set_user_presence: virtual function for matrix_api_set_user_presence()
* @update_pusher: virtual function for matrix_api_update_pusher()
* @get_pushers: virtual function for matrix_api_get_pushers()
* @delete_pusher: virtual function for matrix_api_delete_pusher()
* @get_pusher: virtual function for matrix_api_get_pusher()
* @add_pusher: virtual function for matrix_api_add_pusher()
* @toggle_pusher: virtual function for matrix_api_toggle_pusher()
* @create_room: virtual function for matrix_api_create_room()
* @delete_room_alias: virtual function for matrix_api_delete_room_alias()
* @get_room_id: virtual function for matrix_api_get_room_id()
* @create_room_alias: virtual function for matrix_api_create_room_alias()
* @list_public_rooms: virtual function for matrix_api_list_public_rooms()
* @ban_user: virtual function for matrix_api_ban_user()
* @forget_room: virtual function for matrix_api_forget_room()
* @invite_user_3rdparty: virtual function for matrix_api_invite_user_3rdparty()
* @invite_user: virtual function for matrix_api_invite_user()
* @join_room: virtual function for matrix_api_join_room()
* @leave_room: virtual function for matrix_api_leave_room()
* @event_stream: virtual function for matrix_api_event_stream()
* @get_event: virtual function for matrix_api_get_event()
* @initial_sync: virtual function for matrix_api_initial_sync()
* @get_event_context: virtual function for matrix_api_get_event_context()
* @initial_sync_room: virtual function for matrix_api_initial_sync_room()
* @list_room_members: virtual function for matrix_api_list_room_members()
* @list_room_messages: virtual function for matrix_api_list_room_messages()
* @send_event_receipt: virtual function for matrix_api_send_event_receipt()
* @redact_event: virtual function for matrix_api_redact_event()
* @send_message_event: virtual function for matrix_api_send_message_event()
* @get_room_state: virtual function for matrix_api_get_room_state()
* @send_room_event: virtual function for matrix_api_send_room_event()
* @notify_room_typing: virtual function for matrix_api_notify_room_typing()
* @sync: virtual function for matrix_api_sync()
* @create_filter: virtual function for matrix_api_create_filter()
* @download_filter: virtual function for matrix_api_download_filter()
* @whois: virtual function for matrix_api_whois()
* @versions: virtual function for matrix_api_versions()
* @login: virtual function for matrix_api_login()
* @token_refresh: virtual function for matrix_api_token_refresh()
* @get_3pids: virtual function for matrix_api_get_3pids()
* @add_3pid: virtual function for matrix_api_add_3pid()
* @change_password: virtual function for matrix_api_change_password()
* @get_profile: virtual function for matrix_api_get_profile()
* @get_avatar_url: virtual function for matrix_api_get_avatar_url()
* @set_avatar_url: virtual function for matrix_api_set_avatar_url()
* @get_display_name: virtual function for matrix_api_get_display_name()
* @set_display_name: virtual function for matrix_api_set_display_name()
* @register_account: virtual function for matrix_api_register_account()
* @set_account_data: virtual function for matrix_api_set_account_data()
* @get_room_tags: virtual function for matrix_api_get_room_tags()
* @delete_room_tag: virtual function for matrix_api_delete_room_tag()
* @add_room_tag: virtual function for matrix_api_add_room_tag()
* @get_turn_server: virtual function for matrix_api_get_turn_server()
*
* The interface vtable for #MatrixAPI
*/
/**
* MatrixAPICallback:
* @api: A #MatrixAPI implementation
* @content_type: the content_type of the response
* @json_content: (allow-none): the JSON content of the response, as a
* #JsonNode
* @raw_content: (allow-none): the raw content of the response
* @user_data: User data specified when calling original request function
* @err: a #GError. It will hold any errors from the underlying API
* (including communication or type errors)
*
* A callback function to use with API calls. Either @json_content or
* @raw_content will be set.
*/
G_DEFINE_INTERFACE(MatrixAPI, matrix_api, G_TYPE_OBJECT);
static void
matrix_api_default_init(MatrixAPIInterface *iface)
{
/**
* MatrixAPI:token:
*
* The token to use for authorization. The matrix_api_login() and
* matrix_api_register_account() calls must set this
* automatically.
*/
g_object_interface_install_property(
iface,
g_param_spec_string("token", "Authorization token",
"The authorization token to use in requests",
NULL,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
* MatrixAPI:refresh-token:
*
* The token to use for refreshing the authorization token. It is
* issued by the server after a successful registration, login,
* and token refresh, but can also be changed with
* matrix_api_set_refresh_token() (or setting this property).
*/
g_object_interface_install_property(
iface,
g_param_spec_string("refresh-token", "Refresh token",
"The token issued by the server for authorization token renewal",
NULL,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
* MatrixAPI:user-id:
*
* The Matrix user ID that is currently authenticated to the
* server. It is set by the registration and login processes
* automatically, and cannot be set from outside.
*/
g_object_interface_install_property(
iface,
g_param_spec_string("user-id", "User ID",
"The Matrix user ID that is authenticated to the server",
NULL,
G_PARAM_READABLE));
/**
* MatrixAPI:homeserver:
*
* The Matrix home server, as it calls itself. It is filled
* automatically by login and register calls.
*/
g_object_interface_install_property(
iface,
g_param_spec_string("homeserver", "Homeserver",
"The home server, as it calls itself",
NULL,
G_PARAM_READABLE));
}
/* Property getters and setters */
/**
* matrix_api_get_token:
* @api: a #MatrixAPI implementation
*
* Get the authorization token currently set. See
* matrix_api_set_token() for limitations.
*
* Returns: (transfer none) (allow-none): the authorization token that
* will be used in subsequent requests, or %NULL if none
* set. The returned value is owned by the @api object and
* should not be freed nor modified
*/
const gchar *
matrix_api_get_token(MatrixAPI *api)
{
g_return_val_if_fail(MATRIX_IS_API(api), NULL);
return MATRIX_API_GET_IFACE(api)
->get_token(api);
}
/**
* matrix_api_set_token:
* @api: a #MatrixAPI implementation
* @token: the authorization token to set
*
* Set the authorization token to use in subsequent requests.
*
* <warning><para>Some implementations, like #MatrixHTTPAPI, use
* asynchronous requests. This means that pending requests will use
* the old token and thus, may fail because of this.</para></warning>
*/
void
matrix_api_set_token(MatrixAPI *api, const gchar *token)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->set_token(api, token);
}
/**
* matrix_api_get_refresh_token:
* @api: a #MatrixAPI implementation
*
* Get the refresh token currently set. See matrix_api_set_token() for
* limitations.
*
* Returns: (transfer none) (allow-none): the refresh token to be used
* for authorization token refreshment, or %NULL if there is
* none set. The returned value is owned by the @api object
* and should not be freed nor modified
*/
const gchar *
matrix_api_get_refresh_token(MatrixAPI *api)
{
g_return_val_if_fail(MATRIX_IS_API(api), NULL);
return MATRIX_API_GET_IFACE(api)
->get_refresh_token(api);
}
/**
* matrix_api_set_refresh_token:
* @api: a #MatrixAPI implementation
* @refresh_token: the refresh token to set
*
* Set the refresh token to be used in subsequent requests. See
* matrix_api_set_token() for limitations.
*/
void
matrix_api_set_refresh_token(MatrixAPI *api, const gchar *refresh_token)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->set_refresh_token(api, refresh_token);
}
/**
* matrix_api_get_user_id:
* @api: a #MatrixAPI implementation
*
* Get the Matrix user ID that is currently authenticated with the
* server.
*
* Returns: (transfer none) (allow-none): the Matrix user ID
* authenticated by the last successful register or login
* call (ie. matrix_api_login() or
* matrix_api_register_account()). If no user is
* authenticated, this function returns %NULL. The returned
* value is owned by the @api object and should not be freed
* nor modified
*/
const gchar *
matrix_api_get_user_id(MatrixAPI *api)
{
g_return_val_if_fail(MATRIX_IS_API(api), NULL);
return MATRIX_API_GET_IFACE(api)
->get_user_id(api);
}
/**
* matrix_api_get_homeserver:
* @api: a #MatrixAPI implementation
*
* Get the homeserver's name, as it calls itself. It gets set
* automatically by login and register calls, e.g. matrix_api_login()
* or matrix_api_register_account().
*
* Returns: (transfer none) (allow-none): the Matrix homeserver's
* name, as it calls itself. If no homeserver name is reported yet
* (e.g. because login or register wasn't called yet), this function
* returns %NULL.
*/
const gchar *
matrix_api_get_homeserver(MatrixAPI *api)
{
g_return_val_if_fail(MATRIX_IS_API(api), NULL);
return MATRIX_API_GET_IFACE(api)
->get_homeserver(api);
}
/* Media */
/**
* matrix_api_media_download:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @server_name: the server name from the <code>mxc://</code> URI (the
* authority component)
* @media_id: the media ID from the <code>mxc://</code> URI (the path
* component)
* @error: return location for a #GError, or %NULL
*
* Download content from the content repository.
*/
void
matrix_api_media_download(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *server_name,
const gchar *media_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->media_download(api,
callback, user_data,
server_name, media_id, error);
}
/**
* matrix_api_media_thumbnail:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @server_name: the server name from the <code>mxc://</code> URI (the
* authority component)
* @media_id: the media ID from the <code>mxc://</code> URI (the path
* component)
* @width: the desired width of the thumbnail, or 0 to use the default
* @height: the desired height of the thumbnail, or 0 to use the
* default
* @method: the resizing method to use
* @error: return location for a #GError, or %NULL
*
* Download a thumbnail of the content from the content
* repository. The actual thumbnail may not match the size specified.
*/
void
matrix_api_media_thumbnail(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *server_name,
const gchar *media_id,
guint width,
guint height,
MatrixAPIResizeMethod method,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->media_thumbnail(api,
callback, user_data,
server_name, media_id,
width, height, method,
error);
}
/**
* matrix_api_media_upload:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @content_type: (allow-none): the content type of the file being
* uploaded
* @content: (transfer full): the content to be uploaded
* @error: return location for a #GError, or %NULL
*
* Upload some content to the content repository.
*/
void
matrix_api_media_upload(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *content_type,
GByteArray *content,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->media_upload(api, callback, user_data, content_type, content, error);
}
/* Presence */
/**
* matrix_api_get_presence_list:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user whose presence list should be retrieved
* @error: return location for a #GError, or %NULL
*
* Retrieve a list of presence events for every user on this list.
*/
void
matrix_api_get_presence_list(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_presence_list(api, callback, user_data, user_id, error);
}
/**
* matrix_api_update_presence_list:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user whose presence list is being modified
* @drop_ids: (element-type utf8): a list of user IDs to remove
* from the list
* @invite_ids: (element-type utf8): a list of user IDs to add to
* the list
* @error: return location for a #GError, or %NULL
*
* Add or remove users from the specified user's presence list.
*/
void
matrix_api_update_presence_list(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
GList *drop_ids,
GList *invite_ids,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->update_presence_list(api,
callback, user_data,
user_id, drop_ids, invite_ids, error);
}
/**
* matrix_api_get_user_presence:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user whose presence list is being modified
* @error: return location for a #GError, or %NULL
*
* Get the given user's presence state.
*/
void
matrix_api_get_user_presence(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_user_presence(api,
callback, user_data,
user_id, error);
}
/**
* matrix_api_set_user_presence:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user whose presence list is being modified
* @presence: the new presence state
* @status_message: a status message attached to this state
* @error: return location for a #GError, or %NULL
*
* Set the given user's presence. You cannot set the presence of
* another user.
*/
void
matrix_api_set_user_presence(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
MatrixAPIPresence presence,
const gchar *status_message,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->set_user_presence(api,
callback, user_data,
user_id, presence, status_message,
error);
}
/* Push notifications */
/**
* matrix_api_update_pusher:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @pusher: the pusher information
* @error: return location for a #GError, or %NULL
*
* Create, update or delete a pusher for the active user on this
* homeserver.
*/
void
matrix_api_update_pusher(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
MatrixAPIPusher *pusher,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->update_pusher(api,
callback, user_data,
pusher, error);
}
/**
* matrix_api_get_pushers:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @error: return location for a #GError, or %NULL
*
* Retrieve all push rulesets.
*/
void
matrix_api_get_pushers(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_pushers(api, callback, user_data, error);
}
/**
* matrix_api_delete_pusher:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @scope: either <code>global</code> to specify global rules, or
* <code>device/&lt;profile tag&gt;</code> for rules for a
* given <code>profile tag</code>.
* @kind: the kind of rule
* @rule_id: an identifier for the rule
* @error: return location for a #GError, or %NULL
*
* Delete a push rule.
*/
void
matrix_api_delete_pusher(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *scope,
MatrixAPIPusherKind kind,
const gchar *rule_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->delete_pusher(api,
callback, user_data,
scope, kind, rule_id, error);
}
/**
* matrix_api_get_pusher:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @scope: either <code>global</code> to specify global rules, or
* <code>device/&lt;profile tag&gt;</code> for rules for a
* given <code>profile tag</code>.
* @kind: the kind of rule
* @rule_id: an identifier for the rule
* @error: return location for a #GError, or %NULL
*
* Retrieve a specific push rule.
*/
void
matrix_api_get_pusher(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *scope,
MatrixAPIPusherKind kind,
const gchar *rule_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_pusher(api,
callback, user_data,
scope, kind, rule_id, error);
}
/**
* matrix_api_add_pusher:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @scope: either <code>global</code> to specify global rules, or
* <code>device/&lt;profile tag&gt;</code> for rules for a
* given <code>profile tag</code>.
* @kind: the kind of rule
* @rule_id: an identifier for the rule
* @before: (allow-none): make the new rule the next-most important
* than this rule ID
* @after: (allow-none): make the new rule the next-less important
* than this rule ID
* @actions: (element-type utf8): the actions to perform when the
* conditions for this rule are met
* @conditions: (element-type MatrixAPIPusherConditionKind) (allow-none):
* the conditions that must hold true for an event for a
* rule to be applied. A rule with no conditions always
* matches
* @error: return location for a #GError, or %NULL
*
* Add or change a push rule.
*/
void
matrix_api_add_pusher(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *scope,
MatrixAPIPusherKind kind,
const gchar *rule_id,
const gchar *before,
const gchar *after,
GList *actions,
GList *conditions,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->add_pusher(api,
callback, user_data,
scope, kind, rule_id, before, after,
actions, conditions,
error);
}
/**
* matrix_api_toggle_pusher:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): a function to call when the
* request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @scope: either <code>global</code> to specify global rules, or
* <code>device/&lt;profile tag&gt;</code> for rules for a
* given <code>profile tag</code>.
* @kind: the kind of rule
* @rule_id: an identifier for the rule
* @enabled: if %TRUE, the rule will be enabled, otherwise it gets
* disabled
* @error: return location for a #GError, or %NULL
*
* Enable or disable the specified push rule.
*/
void matrix_api_toggle_pusher(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *scope,
MatrixAPIPusherKind kind,
const gchar *rule_id,
gboolean enabled,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->toggle_pusher(api,
callback, user_data,
scope, kind, rule_id, enabled, error);
}
/* Room creation */
/**
* matrix_api_create_room:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): the function to call when
* the request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @preset: a room preset to use
* @room_name: (allow-none): the desired display name for the room
* @room_alias: (allow-none): an alias of the room
* @topic: (allow-none): the topic of the room
* @visibility: the initial visibility of the room
* @creation_content: (allow-none): extra keys to be added to the
* content of m.room.create
* @initial_state: (element-type MatrixAPIStateEvent) (allow-none): A
* list of state events to set in the new room
* @invitees: (element-type utf8) (allow-none): list of user IDs to
* invite to the new room
* @error: return location for a #GError, or %NULL
*
* Create a new room with the given name and invite the users in
* @invitees.
*/
void
matrix_api_create_room(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
MatrixAPIRoomPreset preset,
const gchar *room_name,
const gchar *room_alias,
const gchar *topic,
MatrixAPIRoomVisibility visibility,
JsonNode *creation_content,
GList *initial_state,
GList *invitees,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->create_room(api, callback, user_data,
preset, room_name, room_alias, topic,
visibility, creation_content,
initial_state, invitees,
error);
}
/* Room directory */
/**
* matrix_api_delete_room_alias:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): the function to call when
* the request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_alias: the alias name to remove
* @error: return location for a #GError, or %NULL
*
* Remove the mapping of @room_alias to its room ID
*
* Servers may choose to implement additional access control checks
* here, for instance that room aliases can only be deleted by their
* creator or a server administrator.
*/
void
matrix_api_delete_room_alias(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_alias,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->delete_room_alias(api, callback, user_data, room_alias, error);
}
/**
* matrix_api_get_room_id:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): the function to call when
* the request is finished
* @user_data: (closure) (allow-none): user data to pass to the callback function
* @room_alias: the room alias
* @error: return location for a #GError, or %NULL
*
* Get the room ID corresponding to this room alias.
*/
void
matrix_api_get_room_id(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_alias,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_room_id(api, callback, user_data, room_alias, error);
}
/**
* matrix_api_create_room_alias:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): the function to call when
* the request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room ID to add this alias to
* @room_alias: the room alias to set
* @error: return location for a #GError, or %NULL
*
* Create a new mapping from room alias to room ID.
*/
void
matrix_api_create_room_alias(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
const gchar *room_alias,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->create_room_alias(api,
callback, user_data,
room_id, room_alias,
error);
}
/* Room discovery */
/**
* matrix_api_list_public_rooms:
* @api: a #MatrixAPI implementation
* @callback: (scope async) (allow-none): the function to call when
* the request is finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @error: return location for a #GError, or %NULL
*
* List the public rooms on the server.
*/
void
matrix_api_list_public_rooms(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->list_public_rooms(api, callback, user_data, error);
}
/* Room membership */
/**
* matrix_api_ban_user:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room ID where the user should be banned
* @user_id: the user ID to ban
* @reason: (allow-none): the reason of the ban
* @error: return location for a #GError, or %NULL
*
* Ban the specified user from the specified room. An optional reason
* can be specified.
*/
void
matrix_api_ban_user(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
const gchar *user_id,
const gchar *reason,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->ban_user(api, callback, user_data, room_id, user_id, reason, error);
}
/**
* matrix_api_forget_room:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room ID to forget
* @error: return location for a #GError, or %NULL
*
* Stop the requesting user remembering about a particular room.
*
* In general, history is a first class citizen in Matrix. After this
* API is called, however, a user will no longer be able to retrieve
* history for this room. If all users on a homeserver forget a room,
* the room is eligible for deletion from that homeserver.
*
* If the user is currently joined to the room, they will implicitly
* leave the room as part of this API call.
*/
void
matrix_api_forget_room(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->forget_room(api, callback, user_data, room_id, error);
}
/**
* matrix_api_invite_user_3rdparty:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room ID to which to invite the user
* @address: the invitee's 3rd party identifier
* @medium: the kind of address being passed in the address field,
* e.g. <code>email</code>
* @id_server: the hostname+port of the identity server which should
* be used for 3rd party identifier lookups
* @error: return location for a #GError, or %NULL
*
* Invite a user to the room by a 3rd party identifier. They do not
* start participating in the room until they actually join the room.
*
* If the identity server does not know a Matrix user identifier for
* the passed third party identifier, the homeserver will issue an
* invitation which can be accepted upon providing proof of ownership
* of the third party identifier.
*/
void matrix_api_invite_user_3rdparty(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
const gchar *address,
const gchar *medium,
const gchar *id_server,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->invite_user_3rdparty(api,
callback, user_data,
room_id, address, medium, id_server,
error);
}
/**
* matrix_api_invite_user:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room ID to invite the user to
* @user_id: the user ID to invite
* @error: return location for a #GError, or %NULL
*
* Invite a user to a room.
*/
void
matrix_api_invite_user(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
const gchar *user_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->invite_user(api, callback, user_data, room_id, user_id, error);
}
/**
* matrix_api_join_room:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room ID to join to
* @error: return location for a #GError, or %NULL
*
* Join a room.
*/
void
matrix_api_join_room(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->join_room(api, callback, user_data, room_id, error);
}
/**
* matrix_api_leave_room:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room ID to kick the user from
* @error: return location for a #GError, or %NULL
*
* Leave a room
*/
void
matrix_api_leave_room(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->leave_room(api, callback, user_data, room_id, error);
}
/* Room participation */
/**
* matrix_api_event_stream:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @from_token: (allow-none): events will be listed from this token
* @timeout: timeout of the request
* @error: return location for a #GError, or %NULL
*
* Get the event stream, optionally beginning from @from_token.
*/
void
matrix_api_event_stream(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *from_token,
gulong timeout,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->event_stream(api, callback, user_data, from_token, timeout, error);
}
/**
* matrix_api_get_event:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @event_id: the event ID to get
* @error: return location for a #GError, or %NULL
*
* Get a single event by event ID.
*/
void
matrix_api_get_event(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *event_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_event(api, callback, user_data, event_id, error);
}
/**
* matrix_api_initial_sync:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @limit: the maximum number of events to get
* @archived: whether to include rooms that the user has left
* @error: return location for a #GError, or %NULL
*
* perform an initial sync of events
*/
void
matrix_api_initial_sync(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
guint limit,
gboolean archived,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->initial_sync(api, callback, user_data, limit, archived, error);
}
/**
* matrix_api_get_event_context:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room to get events from
* @event_id: the event to get context around
* @limit: the maximum number of events to get. If 0, a default value
* is used (10, according to the specification)
* @error: return location for a #GError, or %NULL
*
* Gets a number of events that happened just before and after the
* specified event.
*/
void
matrix_api_get_event_context(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
const gchar *event_id,
guint limit,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_event_context(api,
callback, user_data,
room_id, event_id, limit, error);
}
/**
* matrix_api_initial_sync_room:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room to get the data for
* @error: return location for a #GError, or %NULL
*
* Get a copy of the current state and the most recent messages in a
* room.
*/
void
matrix_api_initial_sync_room(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->initial_sync_room(api, callback, user_data, room_id, error);
}
/**
* matrix_api_list_room_members:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room to get the member events for
* @error: return location for a #GError, or %NULL
*
* Get the list of members for a room.
*/
void
matrix_api_list_room_members(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->list_room_members(api, callback, user_data, room_id, error);
}
/**
* matrix_api_list_room_messages:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room to get the events for
* @from_token: the token to start returning events from. This token
* can be obtained by calling matrix_api_initial_sync()
* or matrix_api_initial_sync_room()
* @direction: the direction of the returned events
* @limit: the maximum number of events to return. If 0, a default
* value will be used (10, according to the specification
* @error: return location for a #GError, or %NULL
*
* Get a list of message and state events for a room.
*/
void
matrix_api_list_room_messages(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
const gchar *from_token,
MatrixAPIEventDirection direction,
guint limit,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->list_room_messages(api,
callback, user_data,
room_id, from_token, direction, limit,
error);
}
/**
* matrix_api_send_event_receipt:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room in which to send the event
* @receipt_type: type of the receipt
* @event_id: the event ID to acknowledge up to
* @receipt: extra receipt information to attach. Note that the server
* will automatically attach the <code>ts</code> field
* @error: return location for a #GError, or %NULL
*
* Update the marker for the given receipt type to the event ID specified.
*/
void
matrix_api_send_event_receipt(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
MatrixAPIReceiptType receipt_type,
const gchar *event_id,
JsonNode *receipt,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->send_event_receipt(api,
callback, user_data,
room_id, receipt_type, event_id, receipt,
error);
}
/**
* matrix_api_redact_event:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room from which to redact the event
* @event_id: the event ID to acknowledge up to
* @txn_id: the transaction ID for this event. Clients should generate
* a unique ID; it will be used by the server to ensure
* idempotency of requests
* @reason: (allow-none): the reason for the event being redacted
* @error: return location for a #GError, or %NULL
*
* Strip all information out of an event which isn't critical to the
* integrity of the server-side representation of the room. This
* cannot be undone.
*
* Users may redact their own events, and any user with a power level
* greater than or equal to <code>redact</code> power level of the
* room may redact events there.
*/
void
matrix_api_redact_event(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
const gchar *event_id,
const gchar *txn_id,
const gchar *reason,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->redact_event(api,
callback, user_data,
room_id, event_id, txn_id, reason,
error);
}
/**
* matrix_api_send_message_event:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room to send the event to
* @event_type: the type of event to send
* @txn_id: the transaction ID for this event. Clients should generate
* a unique ID; it will be used by the server to ensure
* idempotency of requests
* @content: (transfer full): the content of the event as a #JsonNode
* @error: return location for a #GError, or %NULL
*
* Send a message event to the room.
*/
void
matrix_api_send_message_event(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
const gchar *event_type,
const gchar *txn_id,
JsonNode *content,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->send_message_event(api,
callback, user_data,
room_id,
event_type, txn_id,
content, error);
}
/**
* matrix_api_get_room_state:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room ID to get a state for
* @event_type: (allow-none): the type of state to look up
* @state_key: (allow-none): the key of the state to look up. If
* @event_type is %NULL, this parameter is ignored
* @error: return location for a #GError, or %NULL
*
* Look up the contents of a state event in a room. If both
* @event_type and @state_key are empty, get a list of state events
* for that room.
*/
void
matrix_api_get_room_state(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
const gchar *event_type,
const gchar *state_key,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_room_state(api,
callback, user_data,
room_id, event_type, state_key, error);
}
/**
* matrix_api_send_room_event:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @room_id: the room ID to get a state for
* @event_type: the type of state to look up
* @state_key: (allow-none): the key of the state to look up. If
* @event_type is %NULL, this parameter is ignored
* @content: (transfer full): the content of the state event
* @error: return location for a #GError, or %NULL
*
* Send a state event to the room. These events will be overwritten if
* @room_id, @event_type and @state_key all match.
*
* This request cannot use transaction IDs.
*
* The required fields in the body of the request (@content) vary
* depending on the type of the event.
*/
void
matrix_api_send_room_event(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *room_id,
const gchar *event_type,
const gchar *state_key,
JsonNode *content,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->send_room_event(api,
callback, user_data,
room_id, event_type, state_key, content,
error);
}
/**
* matrix_api_notify_room_typing:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user who has started to type
* @room_id: the room in which the user is typing
* @timeout: the length of time in milliseconds to mark this user as
* typing
* @typing: whether the user is typing or not. If %FALSE, @timeout can
* be omitted (ie. set to 0)
* @error: return location for a #GError, or %NULL
*
* Tell the server the user is typing for the next @timeout
* milliseconds. If @typing is %FALSE, it tells the server that the
* user stopped typing.
*/
void
matrix_api_notify_room_typing(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
const gchar *room_id,
guint timeout,
gboolean typing,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->notify_room_typing(api,
callback, user_data,
user_id, room_id, timeout, typing,
error);
}
/**
* matrix_api_sync:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @filter_id: (allow-none): a filter ID created by the filter API
* (e.g. matrix_api_create_filter())
* @filter: (allow-none): a definition on what events to fetch
* @since: (allow-none): a point in time to continue a sync from
* @full_state: if %TRUE, all state events will be returned, even if
* @since is not empty. If %FALSE, and @since is not
* empty, only states which have changed since the point
* indicated by @since will be returned
* @set_presence: controls whether the client is automatically marked
* as online by polling this API.
* @timeout: the maximum time to poll in milliseconds
* @error: return location for a #GError, or %NULL
*
* Synchronize the client's state with the latest state on the
* server. Clients should use this API when they first log in to get
* an initial snapshot of the state on the server and then continue to
* call this API to get incremental details to the state and to
* receive new messages.
*
* Only one of @filter and @filter_id should be specified, or both of
* them should be set to %NULL to receive all events.
*/
void
matrix_api_sync(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *filter_id,
const MatrixAPIFilter *filter,
const gchar *since,
gboolean full_state,
gboolean set_presence,
gulong timeout,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->sync(api,
callback, user_data,
filter_id, filter, since,
full_state, set_presence, timeout,
error);
}
/**
* matrix_api_create_filter:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the ID of the user uploading the filter. An access token
* must be present (either specifying one with
* matrix_api_set_token() or requested from the server via
* matrix_api_register_account() or matrix_api_login().
* @filter: the filter to upload
* @error: return location for a #GError, or %NULL
*
* Upload a new filter definition to the homeserver. It will return a
* filter ID that may be used in future requests.
*/
void
matrix_api_create_filter(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
MatrixAPIFilter *filter,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->create_filter(api,
callback, user_data,
user_id, filter,
error);
}
/**
* matrix_api_download_filter:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user ID to download a filter from
* @filter_id: the filter ID to download
* @error: return location for a #GError, or %NULL
*
* Download a filter.
*/
void
matrix_api_download_filter(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
const gchar *filter_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->download_filter(api,
callback, user_data,
user_id, filter_id, error);
}
/* Search */
/* Server administration */
/**
* matrix_api_whois:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user ID to look up
* @error: return location for a #GError, or %NULL
*
* Get information about a particular user.
*/
void
matrix_api_whois(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->whois(api, callback, user_data, user_id, error);
}
/**
* matrix_api_versions:
* @api: a #MatrixAPI iplementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @error: return location for a #GError, or %NULL
*
* Get the versions of the specification supported by the server.
*/
void
matrix_api_versions(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->versions(api, callback, user_data, error);
}
/* Session management */
/**
* matrix_api_login:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @type: the login type to use
* @content: (allow-none): parameters to pass for the login request
* @error: return location for a #GError, or %NULL
*
* Attempt to login with type @type. Implementations of this method
* must set the token property on a successful login.
*/
void
matrix_api_login(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *type,
const JsonNode *content,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->login(api, callback, user_data, type, content, error);
}
/**
* matrix_api_token_refresh:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @refresh_token: (allow-none): the refresh token that was issued by
* the server
* @error: return location for a #GError, or %NULL
*
* Exchanges a refresh token for a new access token. This is intended
* to be used if the access token has expired. If @refresh_token is
* %NULL, iplementations MUST send the stored refresh token. If it is
* not pesent (e.g. because login hasnt happened yet), this function
* MUST yield an error.
*/
void
matrix_api_token_refresh(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *refresh_token,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->token_refresh(api, callback, user_data, refresh_token, error);
}
/* User data */
/**
* matrix_api_get_3pids:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @error: return location for a #GError, or %NULL
*
* Get a list of the third party identifiers that a homeserver has
* associated with the user's account.
*
* This is not the same as the list of third party identifiers bound
* to the user's Matrix ID in Identity Servers.
*
* Identifiers in this list may be used by the homeserver as, for
* example, identifiers to accept to reset the user's account
* password.
*/
void
matrix_api_get_3pids(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_3pids(api, callback, user_data, error);
}
/**
* matrix_api_add_3pid:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @bind_creds: whether the homeserver should also bind this third
* party identifier to the account's Matrix ID with the
* passed Identity Server.
* @threepid_creds: the credentials to associate with the account
* @error: return location for a #GError, or %NULL
*
* Add contact information to the user's account.
*/
void
matrix_api_add_3pid(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
gboolean bind_creds,
MatrixAPI3PidCredential *threepid_creds,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->add_3pid(api, callback, user_data, bind_creds, threepid_creds, error);
}
/**
* matrix_api_change_password:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @new_password: the new password for the account
* @error: return location for a #GError, or %NULL
*
* Change the active user's password.
*/
void
matrix_api_change_password(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *new_password,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->change_password(api, callback, user_data, new_password, error);
}
/**
* matrix_api_get_profile:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user whose profile to get
* @error: return location for a #GError, or %NULL
*
* Get a user's profile.
*/
void
matrix_api_get_profile(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_profile(api, callback, user_data, user_id, error);
}
/**
* matrix_api_get_avatar_url:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user whose avatar URL to get
* @error: return location for a #GError, or %NULL
*
* Get the URL of the specified user's avatar.
*/
void
matrix_api_get_avatar_url(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_avatar_url(api, callback, user_data, user_id, error);
}
/**
* matrix_api_set_avatar_url:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user whose avatar URL to set
* @avatar_url: the avatar URL info
* @error: return location for a #GError, or %NULL
*
* Set the user's avatar URL.
*/
void
matrix_api_set_avatar_url(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
const gchar *avatar_url,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->set_avatar_url(api, callback, user_data, user_id, avatar_url, error);
}
/**
* matrix_api_get_display_name:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user whose display name to get
* @error: return location for a #GError, or %NULL
*
* Get the user's display name.
*/
void
matrix_api_get_display_name(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_display_name(api, callback, user_data, user_id, error);
}
/**
* matrix_api_set_display_name:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user whose display name to set
* @display_name: the display name info
* @error: return location for a #GError, or %NULL
*
* Set the user's display name.
*/
void
matrix_api_set_display_name(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
const gchar *display_name,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->set_display_name(api,
callback, user_data,
user_id, display_name, error);
}
/**
* matrix_api_register_account:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @bind_email: if %TRUE, the server binds the e-mail used for
* authentication to the Matrix ID with the ID server
* @username: (allow-none): the local part of the desired Matrix
* ID. If omitted, the server will generate a local part
* @password: (allow-none): the desired password for the account
* @error: return location for a #GError, or %NULL
*
* Attempt to register with type @login_type. Implementations of this
* method must set the token property on a successful login.
*/
void
matrix_api_register_account(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
gboolean bind_email,
const gchar *username,
const gchar *password,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->register_account(api, callback, user_data, bind_email,
username, password, error);
}
/**
* matrix_api_set_account_data:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the user to set account data for. An access token must be
* present and be authorized to make requests for this user
* ID
* @room_id: (allow-none): the room to set account data for. If %NULL,
* the account data will be set globally
* @type: the event type of the account data to set. Custom types
* should be namespaced to avoid clashes.
* @content: the content of the account data
* @error: return location for a #GError, or %NULL
*
* Set some account data for the client. This config is only visible
* to the user who set the account data. The config will be synced to
* clients in the top-level account data.
*/
void
matrix_api_set_account_data(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
const gchar *room_id,
const gchar *type,
const JsonNode *content,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->set_account_data(api,
callback, user_data,
user_id, room_id, type, content, error);
}
/**
* matrix_api_get_room_tags:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the ID of the user to get the tags for. An access token
* must be set, and it must be authorised to make requests
* for this user ID
* @room_id: the room to get tags for
* @error: return location for a #GError, or %NULL
*
* List the tags set by a user on a room.
*/
void
matrix_api_get_room_tags(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
const gchar *room_id,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_room_tags(api, callback, user_data, user_id, room_id, error);
}
/**
* matrix_api_delete_room_tag:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the id of the user to remove a tag for
* @room_id: the id of the room to remove the tag from
* @tag: the tag to remove
* @error: return location for a #GError, or %NULL
*
* Remove a tag from the room.
*/
void
matrix_api_delete_room_tag(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
const gchar *room_id,
const gchar *tag,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->delete_room_tag(api,
callback, user_data,
user_id, room_id, tag, error);
}
/**
* matrix_api_add_room_tag:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @user_id: the ID of the user to add the tag for
* @room_id: the ID of the room to add the tag for
* @tag: the tag to add
* @content: extra data for the tag, e.g. ordering
* @error: return location for a #GError, or %NULL
*
* Add a tag to the room.
*/
void
matrix_api_add_room_tag(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
const gchar *user_id,
const gchar *room_id,
const gchar *tag,
JsonNode *content,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->add_room_tag(api,
callback, user_data,
user_id, room_id, tag, content, error);
}
/* VoIP */
/**
* matrix_api_get_turn_server:
* @api: a #MatrixAPI implementation
* @callback: (scope async): the function to call when the request is
* finished
* @user_data: (closure): user data to pass to the callback function
* @callback
* @error: return location for a #GError, or %NULL
*
* Get credentials for the client to use when initiating calls.
*/
void
matrix_api_get_turn_server(MatrixAPI *api,
MatrixAPICallback callback,
gpointer user_data,
GError **error)
{
g_return_if_fail(MATRIX_IS_API(api));
MATRIX_API_GET_IFACE(api)
->get_turn_server(api, callback, user_data, error);
}