diff --git a/docs/reference/matrix-glib/matrix-glib-docs.xml b/docs/reference/matrix-glib/matrix-glib-docs.xml index 86add7e..df707be 100644 --- a/docs/reference/matrix-glib/matrix-glib-docs.xml +++ b/docs/reference/matrix-glib/matrix-glib-docs.xml @@ -19,9 +19,10 @@ Matrix Client + + - Object Hierarchy diff --git a/docs/reference/matrix-glib/matrix-glib-sections.txt b/docs/reference/matrix-glib/matrix-glib-sections.txt index add3f0a..0b4d12b 100644 --- a/docs/reference/matrix-glib/matrix-glib-sections.txt +++ b/docs/reference/matrix-glib/matrix-glib-sections.txt @@ -15,6 +15,47 @@ MatrixClientPrivate matrix_client_get_type +
+matrix-api-types +Fundamental types for MatrixAPI +MatrixAPIFilterRules +matrix_api_filter_rules_new +matrix_api_filter_rules_ref +matrix_api_filter_rules_unref +matrix_api_filter_rules_set_limit +matrix_api_filter_rules_get_limit +matrix_api_filter_rules_set_rooms +matrix_api_filter_rules_add_room +matrix_api_filter_rules_delete_room +matrix_api_filter_rules_get_rooms +matrix_api_filter_rules_set_excluded_rooms +matrix_api_filter_rules_add_excluded_room +matrix_api_filter_rules_delete_excluded_room +matrix_api_filter_rules_get_excluded_rooms +matrix_api_filter_rules_set_senders +matrix_api_filter_rules_add_sender +matrix_api_filter_rules_delete_sender +matrix_api_filter_rules_get_senders +matrix_api_filter_rules_set_excluded_senders +matrix_api_filter_rules_add_excluded_sender +matrix_api_filter_rules_delete_excluded_sender +matrix_api_filter_rules_get_excluded_senders +matrix_api_filter_rules_set_types +matrix_api_filter_rules_add_type +matrix_api_filter_rules_delete_type +matrix_api_filter_rules_get_types +matrix_api_filter_rules_set_excluded_types +matrix_api_filter_rules_add_excluded_type +matrix_api_filter_rules_delete_excluded_type +matrix_api_filter_rules_get_excluded_types +matrix_api_filter_rules_get_json_node +matrix_api_filter_rules_get_json_data + + +MATRIX_TYPE_API_FILTER_RULES +matrix_api_filter_rules_get_type +
+
matrix-api MatrixAPI @@ -126,8 +167,6 @@ MATRIX_API_ERROR MatrixAPIEventFormat MatrixAPIFilter MatrixAPIRoomFilter -MatrixAPIEventFilter -MatrixAPIPresenceFilter MatrixAPIStateEvent MatrixAPI3PidCredential diff --git a/src/Makefile.am b/src/Makefile.am index 9ee1bf4..5652b3f 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -6,6 +6,7 @@ bin_PROGRAMS = test-client INST_H_SRC_FILES = \ matrix-client.h \ matrix-api.h \ + matrix-api-types.h \ matrix-http-api.h \ $(NULL) @@ -20,6 +21,7 @@ libmatrix_glib_0_0_la_SOURCES = \ matrix-client.c \ matrix-version.c \ matrix-api.c \ + matrix-api-types.c \ matrix-http-api.c \ matrix-enumtypes.c \ $(INST_H_SRC_FILES) \ diff --git a/src/matrix-api-types.c b/src/matrix-api-types.c new file mode 100644 index 0000000..fc1c61b --- /dev/null +++ b/src/matrix-api-types.c @@ -0,0 +1,762 @@ +/* + * 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-types.h" + +/** + * SECTION:matrix-api-types + * @title: Generic types + * @short_description: Generic types for all #MatrixAPI + * implementations + * + * These are the types used by all #MatrixAPI implementations for + * communication with the homeserver. + */ + +/** + * MatrixAPIFilterRules: (ref-func matrix_api_filter_rules_ref) (unref-func matrix_api_filter_rules_unref) + * + * An opaque structure to hold filter rules that can be used to filter + * events in the event stream. It is possible to filter by event type, + * room and sender ID. + */ + +struct _MatrixAPIFilterRules { + guint limit; + GList *rooms; + GList *excluded_rooms; + GList *senders; + GList *excluded_senders; + GList *types; + GList *excluded_types; + guint refcount; +}; + +G_DEFINE_BOXED_TYPE(MatrixAPIFilterRules, matrix_api_filter_rules, + (GBoxedCopyFunc)matrix_api_filter_rules_ref, + (GBoxedFreeFunc)matrix_api_filter_rules_unref); + +/** + * matrix_api_filter_rules_new: + * + * Create a new #MatrixAPIFilterRules object with reference count of + * 1. + * + * Returns: (transfer full): a new #MatrixAPIFilterRules + */ +MatrixAPIFilterRules * +matrix_api_filter_rules_new(void) +{ + MatrixAPIFilterRules *rules; + + rules = g_new0(MatrixAPIFilterRules, 1); + rules->refcount = 1; + + return rules; +} + +static void +matrix_api_filter_rules_free(MatrixAPIFilterRules *rules) +{ + g_list_free_full(rules->rooms, g_free); + g_list_free_full(rules->excluded_rooms, g_free); + g_list_free_full(rules->senders, g_free); + g_list_free_full(rules->excluded_senders, g_free); + g_list_free_full(rules->types, g_free); + g_list_free_full(rules->excluded_types, g_free); + + g_free(rules); +} + +/** + * matrix_api_filter_rules_ref: + * @rules: a #MatrixAPIFilterRules + * + * Increase reference count of @rules by one. + * + * Returns: (transfer none): the same #MatrixAPIFilterRules + */ +MatrixAPIFilterRules * +matrix_api_filter_rules_ref(MatrixAPIFilterRules *rules) +{ + rules->refcount++; + + return rules; +} + +/** + * matrix_api_filter_rules_unref: + * @rules: a #MatrixAPIFilterRules + * + * Decrease reference count of @rules by one. If reference count + * reaches zero, @rules is freed. + */ +void +matrix_api_filter_rules_unref(MatrixAPIFilterRules *rules) +{ + if (--rules->refcount == 0) { + matrix_api_filter_rules_free(rules); + } +} + +/** + * matrix_api_filter_rules_set_limit: + * @rules: a #MatrixAPIFilterRules + * @limit: (in): the maximum number of events to return. + * + * Set the maximum number of events to return by the filter. If @limit + * is 0, no limit will be applied. + */ +void +matrix_api_filter_rules_set_limit(MatrixAPIFilterRules *rules, guint limit) +{ + rules->limit = limit; +} + +/** + * matrix_api_filter_rules_get_limit: + * @rules: a #MatrixAPIFilterRules + * + * Get the current limit set in @rules. + * + * Returns: the limit currently set + */ +guint +matrix_api_filter_rules_get_limit(MatrixAPIFilterRules *rules) +{ + return rules->limit; +} + +/** + * matrix_api_filter_rules_set_senders: + * @rules: a #MatrixAPIFilterRules + * @senders: (in) (element-type utf8) (transfer full) (allow-none): + * a list of Matrix user IDs. Events from these users will + * be included in the filtered event list.If %NULL then all + * senders are included. See + * matrix_api_filter_rules_add_sender() for wildcarding + * possibilities + * + * Set the list of user IDs to include in the filtered events. @rules + * takes ownership of @senders, so it should not be freed nor modified + * directly after this call. + */ +void +matrix_api_filter_rules_set_senders(MatrixAPIFilterRules *rules, GList *senders) +{ + g_list_free_full(rules->senders, g_free); + rules->senders = senders; +} + +/** + * matrix_api_filter_rules_add_sender: + * @rules: a #MatrixAPIFilterRules + * @sender: (in): a Matrix user ID to add to the included senders + * list. A * can be used as a wildcard to match + * any sequence of characters + * + * Add @sender to the list of user IDs to include in the filtered + * event list. If @sender is already included in the senders list, + * nothing happens. + */ +void +matrix_api_filter_rules_add_sender(MatrixAPIFilterRules *rules, + const gchar *sender) +{ + g_return_if_fail(sender != NULL); + + if (!g_list_find_custom(rules->senders, sender, (GCompareFunc)g_strcmp0)) { + rules->senders = g_list_prepend(rules->senders, g_strdup(sender)); + } +} + +/** + * matrix_api_filter_rules_delete_sender: + * @rules: a #MatrixAPIFilterRules + * @sender: (in): the user ID to remove from the senders list + * + * Remove @sender from the list of user IDs to include in the filtered + * event list. + */ +void +matrix_api_filter_rules_delete_sender(MatrixAPIFilterRules *rules, + const gchar *sender) +{ + GList *sender_element; + + g_return_if_fail(sender != NULL); + + while (sender_element = g_list_find_custom(rules->senders, sender, + (GCompareFunc)g_strcmp0)) { + rules->senders = g_list_remove_link(rules->senders, sender_element); + g_list_free_full(sender_element, g_free); + } +} + +/** + * matrix_api_filter_rules_get_senders: + * @rules: a #MatrixAPIFilterRules + * + * Get the list of user IDs that will be included in the filtered + * events. + * + * Returns: (element-type utf8) (allow-none) (transfer none): the + * list of user IDs. The returned value is owned by @rules + * and should not be freed nor modified + */ +const GList * +matrix_api_filter_rules_get_senders(MatrixAPIFilterRules *rules) +{ + return rules->senders; +} + +/** + * matrix_api_filter_rules_set_excluded_senders: + * @rules: a #MatrixAPIFilterRules + * @senders: (in) (element-type utf8) (transfer full) (allow-none): + * a list of Matrix user IDs. Events from these users will + * be included in the filtered event list.If %NULL then all + * senders are included. See + * matrix_api_filter_rules_add_sender() for wildcarding + * possibilities + * + * Set the list of Matrix user IDs to exclude from the filtered + * events. A matching sender will be excluded even if it is listed in + * the senders list (specified by + * e.g. matrix_api_filter_rules_set_senders()). @rules takes + * ownership of @senders, so it should not be freed nor modified + * directly after this call. + */ +void +matrix_api_filter_rules_set_excluded_senders(MatrixAPIFilterRules *rules, + GList *senders) +{ + g_list_free_full(rules->excluded_senders, g_free); + rules->excluded_senders = senders; +} + +/** + * matrix_api_filter_rules_add_excluded_sender: + * @rules: a #MatrixAPIFilterRules + * @sender: (in): a Matrix user ID to add to the excluded senders + * list. See matrix_api_filter_rules_add_sender() for + * wildcarding possibilities + * + * Add @sender to the list of user IDs to exclude from the filtered + * event list. If @sender is already in the excluded senders list, + * nothing happens. + */ +void +matrix_api_filter_rules_add_excluded_sender(MatrixAPIFilterRules *rules, + const gchar *sender) +{ + g_return_if_fail(sender != NULL); + + if (!g_list_find_custom(rules->excluded_senders, sender, + (GCompareFunc)g_strcmp0)) { + rules->excluded_senders = g_list_prepend(rules->excluded_senders, + g_strdup(sender)); + } +} + +/** + * matrix_api_filter_rules_delete_excluded_sender: + * @rules: a #MatrixAPIFilterRules + * @sender: (in): the Matrix user ID to remove from the excluded + * senders list + * + * Remove @sender from the list of user IDs to exclude from the + * filtered event list. + */ +void +matrix_api_filter_rules_delete_excluded_sender(MatrixAPIFilterRules *rules, + const gchar *sender) +{ + GList *sender_element; + + g_return_if_fail(sender != NULL); + + while (sender_element = g_list_find_custom(rules->excluded_senders, sender, + (GCompareFunc)g_strcmp0)) { + rules->excluded_senders = g_list_remove_link(rules->excluded_senders, + sender_element); + g_list_free_full(sender_element, g_free); + } +} + +/** + * matrix_api_filter_rules_get_excluded_senders: + * @rules: a #MatrixAPIFilterRules + * + * Get the list of user IDs that will be excluded in the filtered + * events. + * + * Returns: (element-type utf8) (allow-none) (transfer none): the + * list of user IDs to be excluded. The returned value is + * owned by @rules and should not be freed nor modified. + */ +const GList * +matrix_api_filter_rules_get_excluded_senders(MatrixAPIFilterRules *rules) +{ + return rules->excluded_senders; +} + +/** + * matrix_api_filter_rules_set_rooms: + * @rules: a #MatrixAPIFilterRules + * @rooms: (in) (element-type utf8) (transfer full) (allow-none): a + * list of room IDs. Events from these rooms will be included + * in the filtered event list.If %NULL then all rooms are + * included. See matrix_api_filter_rules_add_sender() for + * wildcarding possibilities + * + * Set the list of room IDs to include in the filtered events. @rules + * takes ownership of @rooms, so it should not be freed nor modified + * directly after this call. + */ +void +matrix_api_filter_rules_set_rooms(MatrixAPIFilterRules *rules, GList *rooms) +{ + g_list_free_full(rules->rooms, g_free); + rules->rooms = rooms; +} + +/** + * matrix_api_filter_rules_add_room: + * @rules: a #MatrixAPIFilterRules + * @room: (in): a room ID to add to the included rooms list. See + * matrix_api_filter_rules_add_sender() for wildcarding + * possibilities + * + * Add @room to the list of room IDs to include in the filtered + * event list. If @room is already included in the rooms list, + * nothing happens. + */ +void +matrix_api_filter_rules_add_room(MatrixAPIFilterRules *rules, + const gchar *room) +{ + g_return_if_fail(room != NULL); + + if (!g_list_find_custom(rules->rooms, room, (GCompareFunc)g_strcmp0)) { + rules->rooms = g_list_prepend(rules->rooms, g_strdup(room)); + } +} + +/** + * matrix_api_filter_rules_delete_room: + * @rules: a #MatrixAPIFilterRules + * @room: (in): the room ID to remove from the rooms list + * + * Remove @room from the list of room IDs to include in the filtered + * event list. + */ +void +matrix_api_filter_rules_delete_room(MatrixAPIFilterRules *rules, + const gchar *room) +{ + GList *room_element; + + g_return_if_fail(room != NULL); + + while (room_element = g_list_find_custom(rules->rooms, room, + (GCompareFunc)g_strcmp0)) { + rules->rooms = g_list_remove_link(rules->rooms, room_element); + g_list_free_full(room_element, g_free); + } +} + +/** + * matrix_api_filter_rules_get_rooms: + * @rules: a #MatrixAPIFilterRules + * + * Get the list of room IDs that will be included in the filtered + * events. + * + * Returns: (element-type utf8) (allow-none) (transfer none): the + * list of room IDs. The returned value is owned by @rules + * and should not be freed nor modified + */ +const GList * +matrix_api_filter_rules_get_rooms(MatrixAPIFilterRules *rules) +{ + return rules->rooms; +} + +/** + * matrix_api_filter_rules_set_excluded_rooms: + * @rules: a #MatrixAPIFilterRules + * @rooms: (in) (element-type utf8) (transfer full) (allow-none): a + * list of room IDs. Events from these rooms will be included + * in the filtered event list.If %NULL, then all rooms are + * included. See matrix_api_filter_rules_add_sender() for + * wildcarding possibilities + * + * Set the list of room IDs to exclude from the filtered events. A + * matching room will be excluded even if it is listed in the rooms + * list (specified by + * e.g. matrix_api_filter_rules_set_rooms()). @rules takes ownership + * of @rooms, so it should not be freed nor modified directly after + * this call. + */ +void +matrix_api_filter_rules_set_excluded_rooms(MatrixAPIFilterRules *rules, + GList *rooms) +{ + g_list_free_full(rules->excluded_rooms, g_free); + rules->excluded_rooms = rooms; +} + +/** + * matrix_api_filter_rules_add_excluded_room: + * @rules: a #MatrixAPIFilterRules + * @room: (in): a room ID to add to the excluded rooms list. See + * matrix_api_filter_rules_add_sender() for wildcarding + * possibilities + * + * Add @room to the list of room IDs to exclude from the filtered + * event list. If @room is already in the excluded rooms list, nothing + * happens. + */ +void +matrix_api_filter_rules_add_excluded_room(MatrixAPIFilterRules *rules, + const gchar *room) +{ + g_return_if_fail(room != NULL); + + if (!g_list_find_custom(rules->excluded_rooms, room, + (GCompareFunc)g_strcmp0)) { + rules->excluded_rooms = g_list_prepend(rules->excluded_rooms, + g_strdup(room)); + } +} + +/** + * matrix_api_filter_rules_delete_excluded_room: + * @rules: a #MatrixAPIFilterRules + * @room: (in): the room ID to remove from the excluded rooms list + * + * Remove @room from the list of room IDs to exclude from the filtered + * event list. + */ +void +matrix_api_filter_rules_delete_excluded_room(MatrixAPIFilterRules *rules, + const gchar *room) +{ + GList *room_element; + + g_return_if_fail(room != NULL); + + while (room_element = g_list_find_custom(rules->excluded_rooms, room, + (GCompareFunc)g_strcmp0)) { + rules->excluded_rooms = g_list_remove_link(rules->excluded_rooms, + room_element); + g_list_free_full(room_element, g_free); + } +} + +/** + * matrix_api_filter_rules_get_excluded_rooms: + * @rules: a #MatrixAPIFilterRules + * + * Get the list of room IDs that will be excluded in the filtered + * events. + * + * Returns: (element-type utf8) (allow-none) (transfer none): the + * list of room IDs to be excluded. The returned value is + * owned by @rules and should not be freed nor modified. + */ +const GList * +matrix_api_filter_rules_get_excluded_rooms(MatrixAPIFilterRules *rules) +{ + return rules->excluded_rooms; +} + +/** + * matrix_api_filter_rules_set_types: + * @rules: a #MatrixAPIFilterRules + * @types: (in) (element-type utf8) (transfer full) (allow-none): a + * list of event types to include. If %NULL then all event + * types are included. See + * matrix_api_filter_rules_add_sender() for wildcarding + * possibilities + * + * Set the list of event types to be included in the filtered events. + */ +void +matrix_api_filter_rules_set_types(MatrixAPIFilterRules *rules, GList *types) +{ + g_list_free_full(rules->types, g_free); + rules->types = types; +} + +/** + * matrix_api_filter_rules_add_type: + * @rules: a #MatrixAPIFilterRules + * @type: (in): an event type to add to the list of included + * events. See matrix_api_filter_rules_add_sender() for + * wildcarding possibilities + * + * Add @type to the list of event types to include in the filtered + * event list. If @type is already included in the types list, nothing + * happens. + */ +void +matrix_api_filter_rules_add_type(MatrixAPIFilterRules *rules, const gchar *type) +{ + g_return_if_fail(type != NULL); + + if (g_list_find_custom(rules->types, type, (GCompareFunc)g_strcmp0)) { + rules->types = g_list_prepend(rules->types, g_strdup(type)); + } +} + +/** + * matrix_api_filter_rules_delete_type: + * @rules: a #MatrixAPIFilterRules + * @type: (in): a type to remove from the list of included event + * types. See matrix_api_filter_rules_add_sender() for + * wildcarding possibilities + * + * Remove @type from the list of excluded event type list. + */ +void +matrix_api_filter_rules_delete_type(MatrixAPIFilterRules *rules, + const gchar *type) +{ + GList *type_element; + + g_return_if_fail(type != NULL); + + while (type_element = g_list_find_custom(rules->types, type, + (GCompareFunc)g_strcmp0)) { + rules->types = g_list_remove_link(rules->types, type_element); + g_list_free_full(type_element, g_free); + } +} + +/** + * matrix_api_filter_rules_get_types: + * @rules: a #MatrixAPIFilterRules + * + * Get the list of event types that will be included in the filtered + * events. + * + * Returns: (element-type utf8) (allow-none) (transfer none): the + * list of event types. The returned values is owned by + * @rules and should not be freed nor modified + */ +const GList * +matrix_api_filter_rules_get_types(MatrixAPIFilterRules *rules) +{ + return rules->types; +} + +/** + * matrix_api_filter_rules_set_excluded_types: + * @rules: a #MatrixAPIFilterRules + * @types: (in) (element-type utf8) (transfer full) (allow-none): a + * list of event types to exclude. If %NULL then no event + * types are excluded. A matching type will be excluded even + * if it is listed in the included types. See + * matrix_api_filter_rules_add_sender() for wildcarding + * possibilities + * + * Set the list of event types to be excluded from the filtered + * events. A matching type will be excluded even if it is listed in + * the types list (specified by + * e.g. matrix_api_filter_rules_set_types()). + */ +void +matrix_api_filter_rules_set_excluded_types(MatrixAPIFilterRules *rules, + GList *types) +{ + g_list_free_full(rules->excluded_types, g_free); + rules->excluded_types = types; +} + +/** + * matrix_api_filter_rules_add_excluded_type: + * @rules: a #MatrixAPIFilterRules + * @type: (in): an event type to add to the excluded event type + * list. See matrix_api_filter_rules_add_sender() for + * wildcarding possibilities + * + * Add @type to the list of excluded event types. + */ +void +matrix_api_filter_rules_add_excluded_type(MatrixAPIFilterRules *rules, + const gchar *type) +{ + g_return_if_fail(type != NULL); + + if (!g_list_find_custom(rules->excluded_types, type, + (GCompareFunc)g_strcmp0)) { + rules->excluded_types = g_list_prepend(rules->excluded_types, + g_strdup(type)); + } +} + +/** + * matrix_api_filter_rules_delete_excluded_type: + * @rules: a #MatrixAPIFilterRules + * @type: (in): the event type to be removed from the excluded types + * list + * + * Remove @type from the list of event types to be excluded from the + * filtered event list. + */ +void +matrix_api_filter_rules_delete_excluded_type(MatrixAPIFilterRules *rules, + const gchar *type) +{ + GList *type_element; + + g_return_if_fail(type != NULL); + + while (type_element = g_list_find_custom(rules->excluded_types, type, + (GCompareFunc)g_strcmp0)) { + rules->excluded_types = g_list_remove_link(rules->excluded_types, + type_element); + g_list_free_full(type_element, g_free); + } +} + +/** + * matrix_api_filter_rules_get_excluded_types: + * @rules: a #MatrixAPIFilterRules + * + * Get the list of event types that will be excluded from the filtered + * events. + * + * Returns: (element-type utf8) (allow-none) (transfer none): the + * list of event types. The returned value is owned by + * @rules and should not be freed nor modified + */ +const GList * +matrix_api_filter_rules_get_excluded_types(MatrixAPIFilterRules *rules) +{ + return rules->excluded_types; +} + +static void +json_add_string(gchar *str, JsonBuilder *builder) +{ + json_builder_add_string_value(builder, str); +} + +/** + * matrix_api_filter_rules_get_json_node: + * @rules: a #MatrixAPIFilterRules + * + * Gets the #JsonNode representation of this filtering ruleset. + * + * Returns: (transfer full): the JSON representation of the filtering + * data as a #JsonNode + */ +JsonNode * +matrix_api_filter_rules_get_json_node(MatrixAPIFilterRules *rules) +{ + JsonBuilder *builder; + JsonNode *node; + + builder = json_builder_new(); + json_builder_begin_object(builder); + + json_builder_set_member_name(builder, "limit"); + json_builder_add_int_value(builder, rules->limit); + + if (rules->rooms) { + json_builder_set_member_name(builder, "rooms"); + json_builder_begin_array(builder); + g_list_foreach(rules->rooms, (GFunc)json_add_string, builder); + json_builder_end_array(builder); + } + + if (rules->excluded_rooms) { + json_builder_set_member_name(builder, "not_rooms"); + json_builder_begin_array(builder); + g_list_foreach(rules->excluded_rooms, (GFunc)json_add_string, builder); + json_builder_end_array(builder); + } + + if (rules->senders) { + json_builder_set_member_name(builder, "senders"); + json_builder_begin_array(builder); + g_list_foreach(rules->senders, (GFunc)json_add_string, builder); + json_builder_end_array(builder); + } + + if (rules->excluded_senders) { + json_builder_set_member_name(builder, "not_senders"); + json_builder_begin_array(builder); + g_list_foreach(rules->excluded_senders, + (GFunc)json_add_string, builder); + json_builder_end_array(builder); + } + + if (rules->types) { + json_builder_set_member_name(builder, "types"); + json_builder_begin_array(builder); + g_list_foreach(rules->types, (GFunc)json_add_string, builder); + json_builder_end_array(builder); + } + + if (rules->excluded_types) { + json_builder_set_member_name(builder, "not_types"); + json_builder_begin_array(builder); + g_list_foreach(rules->excluded_types, (GFunc)json_add_string, builder); + json_builder_end_array(builder); + } + + json_builder_end_object(builder); + + node = json_builder_get_root(builder); + g_object_unref(builder); + + return node; +} + +/** + * matrix_api_filter_rules_get_json_data: + * @rules: a #MatrixAPIFilterRules + * @datalen: (out): storage for the the length of the JSON data or + * %NULL + * + * Gets the string representation of these filtering rules, as a JSON + * object. + * + * Returns: (transfer full): the JSON representation of the filtering + * rule data as a string + */ +gchar * +matrix_api_filter_rules_get_json_data(MatrixAPIFilterRules *rules, + gsize *datalen) +{ + JsonGenerator *generator; + JsonNode *node = matrix_api_filter_rules_get_json_node(rules); + gchar *data; + + generator = json_generator_new(); + json_generator_set_root(generator, node); + json_node_free(node); + + data = json_generator_to_data(generator, datalen); + + return data; +} diff --git a/src/matrix-api-types.h b/src/matrix-api-types.h new file mode 100644 index 0000000..0c3f871 --- /dev/null +++ b/src/matrix-api-types.h @@ -0,0 +1,82 @@ +/* + * 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 + * . + */ + +#ifndef __MATRIX_API_TYPES_H__ +#define __MATRIX_API_TYPES_H__ + +#include +#include + +typedef struct _MatrixAPIFilterRules MatrixAPIFilterRules; + +GType matrix_api_filter_rules_get_type(void); +#define MATRIX_TYPE_API_FILTER_RULES (matrix_api_filter_rules_get_type()) + +MatrixAPIFilterRules *matrix_api_filter_rules_new(void); +MatrixAPIFilterRules *matrix_api_filter_rules_ref(MatrixAPIFilterRules *rules); +void matrix_api_filter_rules_unref(MatrixAPIFilterRules *rules); +void matrix_api_filter_rules_set_limit(MatrixAPIFilterRules *rules, + guint limit); +guint matrix_api_filter_rules_get_limit(MatrixAPIFilterRules *rules); +void matrix_api_filter_rules_set_rooms(MatrixAPIFilterRules *rules, + GList *rooms); +void matrix_api_filter_rules_add_room(MatrixAPIFilterRules *rules, + const gchar *room); +void matrix_api_filter_rules_delete_room(MatrixAPIFilterRules *rules, + const gchar *room); +const GList *matrix_api_filter_rules_get_rooms(MatrixAPIFilterRules *rules); +void matrix_api_filter_rules_set_excluded_rooms(MatrixAPIFilterRules *rules, + GList *rooms); +void matrix_api_filter_rules_add_excluded_room(MatrixAPIFilterRules *rules, + const gchar *room); +void matrix_api_filter_rules_delete_excluded_room(MatrixAPIFilterRules *rules, + const gchar *room); +const GList *matrix_api_filter_rules_get_excluded_rooms(MatrixAPIFilterRules *rules); +void matrix_api_filter_rules_set_senders(MatrixAPIFilterRules *rules, + GList *senders); +void matrix_api_filter_rules_add_sender(MatrixAPIFilterRules *rules, + const gchar *sender); +void matrix_api_filter_rules_delete_sender(MatrixAPIFilterRules *rules, + const gchar *sender); +const GList *matrix_api_filter_rules_get_senders(MatrixAPIFilterRules *rules); +void matrix_api_filter_rules_set_excluded_senders(MatrixAPIFilterRules *rules, + GList *senders); +void matrix_api_filter_rules_add_excluded_sender(MatrixAPIFilterRules *rules, + const gchar *sender); +void matrix_api_filter_rules_delete_excluded_sender(MatrixAPIFilterRules *rules, + const gchar *sender); +const GList *matrix_api_filter_rules_get_excluded_senders(MatrixAPIFilterRules *rules); +void matrix_api_filter_rules_set_types(MatrixAPIFilterRules *rules, + GList *types); +void matrix_api_filter_rules_add_type(MatrixAPIFilterRules *rules, + const gchar *type); +void matrix_api_filter_rules_delete_type(MatrixAPIFilterRules *rules, + const gchar *type); +const GList *matrix_api_filter_rules_get_types(MatrixAPIFilterRules *rules); +void matrix_api_filter_rules_set_excluded_types(MatrixAPIFilterRules *rules, + GList *types); +void matrix_api_filter_rules_add_excluded_type(MatrixAPIFilterRules *rules, + const gchar *type); +void matrix_api_filter_rules_delete_excluded_type(MatrixAPIFilterRules *rules, + const gchar *type); +const GList *matrix_api_filter_rules_get_excluded_types(MatrixAPIFilterRules *rules); +JsonNode *matrix_api_filter_rules_get_json_node(MatrixAPIFilterRules *rules); +gchar *matrix_api_filter_rules_get_json_data(MatrixAPIFilterRules *rules, + gsize *datalen); + +#endif /* __MATRIX_API_TYPES_H__ */ diff --git a/src/matrix-api.c b/src/matrix-api.c index 369e495..76ddcc7 100644 --- a/src/matrix-api.c +++ b/src/matrix-api.c @@ -22,7 +22,7 @@ * SECTION:matrix-api * @title: MatrixAPI * @short_description: An interface for actual API implementations, - * like #MatrixHTTPAPI + * like #MatrixHTTPAPI * * This interface provides a skeleton for all API functionality for * client communication with a Matrix.org homeserver. @@ -307,40 +307,6 @@ * communication. */ -/** - * MatrixAPIEventFilter: - * @rooms: (element-type GString): a list of room IDs to include. If - * %NULL, all rooms will be included. A * can be - * used as a wildcard to match any sequence of characters - * @not_rooms: (element-type GString): a list of room IDs to - * exclude. If %NULL, no rooms are excluded. A matching - * room will be excluded even if it is listed in @rooms. A - * * can be used as a wildcard to match any - * sequence of characters - * @limit: the maximum number of events to return. If 0, - * no limit is applied - * @senders: (element-type GString): a list of senders IDs to - * include. If %NULL then all senders are included. A - * * can be used as a wildcard to match any - * sequence of characters - * @not_senders: (element-type GString): a list of sender IDs to - * exclude. If %NULL then no senders are excluded. A - * matching sender will be excluded even if it is listed - * in the @senders filter. A * can be used - * as a wildcard to match any sequence of characters - * @types: (element-type GString): a list of event types to - * include. If %NULL then all event types are included. A - * * can be used as a wildcard to match any - * sequence of characters - * @not_types: (element-type GString): a list of event types to - * exclude. If this list is absent then no event types are - * excluded. A matching type will be excluded even if it - * is listed in the @types filter. A * can be - * used as a wildcard to match any sequence of characters - * - * A struct to hold event filters. - */ - /** * MatrixAPIRoomFilter: * @ephemeral: the events that aren't recorded in the room history, @@ -352,32 +318,6 @@ * A struct to hold a room event filter */ -/** - * MatrixAPIPresenceFilter: - * @limit: the maximum number of events to return. If 0, - * no limit will be applied - * @senders: (element-type GString): a list of senders IDs to - * include. If %NULL then all senders are included. A - * * can be used as a wildcard to match any - * sequence of characters - * @not_senders: (element-type GString): a list of sender IDs to - * exclude. If %NULL then no senders are excluded. A - * matching sender will be excluded even if it is listed - * in the @senders filter. A * can be used - * as a wildcard to match any sequence of characters - * @types: (element-type GString): a list of event types to - * include. If %NULL then all event types are included. A - * * can be used as a wildcard to match any - * sequence of characters - * @not_types: (element-type GString): a list of event types to - * exclude. If %NULL then no event types are excluded. A - * matching type will be excluded even if it is listed in - * the @types filter. A * can be used as a - * wildcard to match any sequence of characters - * - * A struct to hold a presence filter. - */ - /** * MatrixAPIFilter: * @event_fields: (element-type GString): list of event fields to @@ -614,12 +554,13 @@ matrix_api_get_homeserver(MatrixAPI *api) * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @user_data: (closure): user data to pass to the callback function + * @callback * @server_name: the server name from the mxc:// URI (the * authority component) * @media_id: the media ID from the mxc:// URI (the path * component) - * @error: (allow-none): a #GError + * @error: return location for a #GError, or %NULL * * Download content from the content repository. */ @@ -644,7 +585,8 @@ matrix_api_media_download(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @user_data: (closure): user data to pass to the callback function + * @callback * @server_name: the server name from the mxc:// URI (the * authority component) * @media_id: the media ID from the mxc:// URI (the path @@ -653,7 +595,7 @@ matrix_api_media_download(MatrixAPI *api, * @height: the desired height of the thumbnail, or 0 to use the * default * @method: the resizing method to use - * @error: (allow-none): a #GError + * @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. @@ -684,11 +626,12 @@ matrix_api_media_thumbnail(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @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: the content to be uploaded - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Upload some content to the content repository. */ @@ -713,9 +656,10 @@ matrix_api_media_upload(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @user_data: (closure): user data to pass to the callback function + * @callback * @user_id: the user whose presence list should be retrieved - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Retrieve a list of presence events for every user on this list. */ @@ -737,13 +681,14 @@ matrix_api_get_presence_list(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @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 GString): a list of user IDs to remove * from the list * @invite_ids: (element-type GString): a list of user IDs to add to * the list - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Add or remove users from the specified user's presence list. */ @@ -769,9 +714,10 @@ matrix_api_update_presence_list(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @user_data: (closure): user data to pass to the callback function + * @callback * @user_id: the user whose presence list is being modified - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Get the given user's presence state. */ @@ -795,11 +741,12 @@ matrix_api_get_user_presence(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Set the given user's presence. You cannot set the presence of * another user. @@ -829,9 +776,10 @@ matrix_api_set_user_presence(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @user_data: (closure): user data to pass to the callback function + * @callback * @pusher: the pusher information - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Modify a pushers for the active user on this homeserver. */ @@ -855,8 +803,9 @@ matrix_api_modify_pusher(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback - * @error: a #GError + * @user_data: (closure): user data to pass to the callback function + * @callback + * @error: return location for a #GError, or %NULL * * Retrieve all push rulesets. */ @@ -877,13 +826,14 @@ matrix_api_get_pushers(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @user_data: (closure): user data to pass to the callback function + * @callback * @scope: either global to specify global rules, or * device/<profile tag> for rules for a * given profile tag. * @kind: the kind of rule * @rule_id: an identifier for the rule - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Delete a push rule. */ @@ -909,13 +859,14 @@ matrix_api_delete_pusher(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @user_data: (closure): user data to pass to the callback function + * @callback * @scope: either global to specify global rules, or * device/<profile tag> for rules for a * given profile tag. * @kind: the kind of rule * @rule_id: an identifier for the rule - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Retrieve a specific push rule. */ @@ -941,7 +892,8 @@ matrix_api_get_pusher(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @user_data: (closure): user data to pass to the callback function + * @callback * @scope: either global to specify global rules, or * device/<profile tag> for rules for a * given profile tag. @@ -957,7 +909,7 @@ matrix_api_get_pusher(MatrixAPI *api, * the conditions that must hold true for an event for a * rule to be applied. A rule with no conditions always * matches - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Add or change a push rule. */ @@ -989,7 +941,8 @@ matrix_api_add_pusher(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): a function to call when the * request is finished - * @user_data: user data to pass to the callback function @callback + * @user_data: (closure): user data to pass to the callback function + * @callback * @scope: either global to specify global rules, or * device/<profile tag> for rules for a * given profile tag. @@ -997,7 +950,7 @@ matrix_api_add_pusher(MatrixAPI *api, * @rule_id: an identifier for the rule * @enabled: if %TRUE, the rule will be enabled, otherwise it gets * disabled - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Enable or disable the specified push rule. */ @@ -1025,7 +978,8 @@ void matrix_api_toggle_pusher(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): the function to call when * the request is finished - * @user_data: (allow-none): user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @preset: a room preset to use * @room_name: (allow-none): the desired name for the room * @room_alias: (allow-none): the alias of the room @@ -1037,7 +991,7 @@ void matrix_api_toggle_pusher(MatrixAPI *api, * list of state events to set in the new room * @invitees: (element-type GString) (allow-none): list of user IDs to * invite to the new room - * @error: (allow-none): a #GError + * @error: return location for a #GError, or %NULL * * Create a new room with the given name and invite the users in * @invitees. @@ -1073,9 +1027,10 @@ matrix_api_create_room(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): the function to call when * the request is finished - * @user_data: (allow-none): user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @room_alias: the alias name to remove - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Remove the mapping of @room_alias to its room ID * @@ -1101,9 +1056,9 @@ matrix_api_delete_room_alias(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): the function to call when * the request is finished - * @user_data: (allow-none): user data to pass to the callback function + * @user_data: (closure) (allow-none): user data to pass to the callback function * @room_alias: the room alias - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Get the room ID corresponding to this room alias. */ @@ -1125,10 +1080,11 @@ matrix_api_get_room_id(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): the function to call when * the request is finished - * @user_data: (allow-none): user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Create a new mapping from room alias to room ID. */ @@ -1156,8 +1112,9 @@ matrix_api_create_room_alias(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async) (allow-none): the function to call when * the request is finished - * @user_data: (allow-none): user data to pass to the callback function - * @error: a #GError + * @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. */ @@ -1180,11 +1137,12 @@ matrix_api_list_public_rooms(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: (allow-none): a #GError + * @error: return location for a #GError, or %NULL * * Ban the specified user from the specified room. An optional reason * can be specified. @@ -1209,9 +1167,10 @@ matrix_api_ban_user(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @room_id: the room ID to forget - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Stop the requesting user remembering about a particular room. * @@ -1241,14 +1200,15 @@ matrix_api_forget_room(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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. email * @id_server: the hostname+port of the identity server which should * be used for 3rd party identifier lookups - * @error: a #GError + * @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. @@ -1281,10 +1241,11 @@ void matrix_api_invite_user_3rdparty(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Invite a user to a room. */ @@ -1307,9 +1268,10 @@ matrix_api_invite_user(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @room_id_or_alias: the room ID or room alias to join to - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Join a room. */ @@ -1331,9 +1293,10 @@ matrix_api_join_room(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @room_id: the room ID to kick the user from - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Leave a room */ @@ -1357,10 +1320,11 @@ matrix_api_leave_room(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Get the event stream, optionally beginning from @from_token. */ @@ -1383,9 +1347,10 @@ matrix_api_event_stream(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @event_id: the event ID to get - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Get a single event by event ID. */ @@ -1407,10 +1372,11 @@ matrix_api_get_event(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * perform an initial sync of events */ @@ -1433,12 +1399,13 @@ matrix_api_initial_sync(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Gets a number of events that happened just before and after the * specified event. @@ -1465,9 +1432,10 @@ matrix_api_get_event_context(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @room_id: the room to get the data for - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Get a copy of the current state and the most recent messages in a * room. @@ -1490,9 +1458,10 @@ matrix_api_initial_sync_room(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @room_id: the room to get the member events for - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Get the list of members for a room. */ @@ -1514,7 +1483,8 @@ matrix_api_list_room_members(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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() @@ -1522,7 +1492,7 @@ matrix_api_list_room_members(MatrixAPI *api, * @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: a #GError + * @error: return location for a #GError, or %NULL * * Get a list of message and state events for a room. */ @@ -1550,13 +1520,14 @@ matrix_api_list_room_messages(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @room_id: the room in which to send the event * @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 ts field - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Update the marker for the given receipt type to the event ID specified. */ @@ -1584,14 +1555,15 @@ matrix_api_send_event_receipt(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @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 @@ -1625,14 +1597,15 @@ matrix_api_redact_event(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: the content of the event as a #JsonNode - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Send a message event to the room. */ @@ -1661,12 +1634,13 @@ matrix_api_send_message_event(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @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 @@ -1694,13 +1668,14 @@ matrix_api_get_room_state(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: the content of the state event - * @error: a #GError + * @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. @@ -1734,14 +1709,15 @@ matrix_api_send_room_event(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @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 @@ -1771,7 +1747,8 @@ matrix_api_notify_room_typing(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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 @@ -1783,7 +1760,7 @@ matrix_api_notify_room_typing(MatrixAPI *api, * @set_presence: controls whether the client is automatically marked * as online by polling this API. * @timeout: the maximum time to poll in milliseconds - * @error: a #GError + * @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 @@ -1821,13 +1798,14 @@ matrix_api_sync(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @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. @@ -1854,10 +1832,11 @@ matrix_api_create_filter(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Download a filter. */ @@ -1886,9 +1865,10 @@ matrix_api_download_filter(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @user_id: the user ID to look up - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Get information about a particular user. */ @@ -1912,10 +1892,11 @@ matrix_api_whois(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: (allow-none): a #GError + * @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. @@ -1939,9 +1920,10 @@ matrix_api_login(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @refresh_token: the refresh token that was issued by the server - * @error: a #GError + * @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. @@ -1966,8 +1948,9 @@ matrix_api_token_refresh(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function - * @error: a #GError + * @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. @@ -1996,12 +1979,13 @@ matrix_api_get_3pids(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Add contact information to the user's account. */ @@ -2024,9 +2008,10 @@ matrix_api_add_3pid(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @new_password: the new password for the account - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Change the active user's password. */ @@ -2048,9 +2033,10 @@ matrix_api_change_password(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @user_id: the user whose profile to get - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Get a user's profile. */ @@ -2072,9 +2058,10 @@ matrix_api_get_profile(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @user_id: the user whose avatar URL to get - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Get the URL of the specified user's avatar. */ @@ -2096,10 +2083,11 @@ matrix_api_get_avatar_url(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Set the user's avatar URL. */ @@ -2122,9 +2110,10 @@ matrix_api_set_avatar_url(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @user_data: (closure): user data to pass to the callback function + * @callback * @user_id: the user whose display name to get - * @error: a #GError + * @error: return location for a #GError, or %NULL * * Get the user's display name. */ @@ -2146,10 +2135,11 @@ matrix_api_get_display_name(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Set the user's display name. */ @@ -2174,13 +2164,14 @@ matrix_api_set_display_name(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @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. @@ -2206,7 +2197,8 @@ matrix_api_register_account(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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 @@ -2215,7 +2207,7 @@ matrix_api_register_account(MatrixAPI *api, * @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: a #GError + * @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 @@ -2244,12 +2236,13 @@ matrix_api_set_account_data(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * List the tags set by a user on a room. */ @@ -2272,11 +2265,12 @@ matrix_api_get_room_tags(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Remove a tag from the room. */ @@ -2302,12 +2296,13 @@ matrix_api_delete_room_tag(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function + * @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: a #GError + * @error: return location for a #GError, or %NULL * * Add a tag to the room. */ @@ -2336,8 +2331,9 @@ matrix_api_add_room_tag(MatrixAPI *api, * @api: a #MatrixAPI implementation * @callback: (scope async): the function to call when the request is * finished - * @user_data: user data to pass to the callback function - * @error: a #GError + * @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. */ diff --git a/src/matrix-api.h b/src/matrix-api.h index d411ac8..8012f45 100644 --- a/src/matrix-api.h +++ b/src/matrix-api.h @@ -22,6 +22,8 @@ #include #include +#include "matrix-api-types.h" + G_BEGIN_DECLS typedef enum { @@ -105,35 +107,17 @@ typedef enum { MATRIX_API_PUSHER_CONDITION_KIND_ROOM_MEMBER_COUNT } MatrixAPIPusherConditionKind; -typedef struct _MatrixAPIPresenceFilter { - guint limit; - GList *senders; - GList *not_senders; - GList *types; - GList *not_types; -} MatrixAPIPresenceFilter; - -typedef struct _MatrixAPIEventFilter { - GList *rooms; - GList *not_rooms; - guint limit; - GList *senders; - GList *not_senders; - GList *types; - GList *not_types; -} MatrixAPIEventFilter; - typedef struct _MatrixAPIRoomFilter { - MatrixAPIEventFilter *ephemeral; + MatrixAPIFilterRules *ephemeral; gboolean include_leave; - MatrixAPIEventFilter *state; - MatrixAPIEventFilter *timeline; + MatrixAPIFilterRules *state; + MatrixAPIFilterRules *timeline; } MatrixAPIRoomFilter; typedef struct _MatrixAPIFilter { GList *event_fields; MatrixAPIEventFormat event_format; - MatrixAPIPresenceFilter *presence; + MatrixAPIFilterRules *presence; MatrixAPIRoomFilter *room; } MatrixAPIFilter;