diff options
Diffstat (limited to 'lib/csapi/create_room.h')
| -rw-r--r-- | lib/csapi/create_room.h | 78 |
1 files changed, 59 insertions, 19 deletions
diff --git a/lib/csapi/create_room.h b/lib/csapi/create_room.h index 79ea2385..60579a83 100644 --- a/lib/csapi/create_room.h +++ b/lib/csapi/create_room.h @@ -23,16 +23,20 @@ namespace QMatrixClient /// apply the events implied by the request in the following order: /// /// 0. A default ``m.room.power_levels`` event, giving the room creator - /// (and not other members) permission to send state events. + /// (and not other members) permission to send state events. Overridden + /// by the ``power_level_content_override`` parameter. /// - /// 1. Events set by the ``preset``. + /// 1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``, + /// ``m.room.history_visibility``, and ``m.room.guest_access`` state events. /// /// 2. Events listed in ``initial_state``, in the order that they are /// listed. /// - /// 3. Events implied by ``name`` and ``topic``. + /// 3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic`` + /// state events). /// - /// 4. Invite events implied by ``invite`` and ``invite_3pid``. + /// 4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with + /// ``membership: invite`` and ``m.room.third_party_invite``). /// /// The available presets do the following with respect to room state: /// @@ -43,6 +47,10 @@ namespace QMatrixClient /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. /// ``public_chat`` ``public`` ``shared`` ``forbidden`` /// ======================== ============== ====================== ================ ========= + /// + /// The server will create a ``m.room.create`` event in the room with the + /// requesting user as the creator, alongside other keys provided in the + /// ``creation_content``. class CreateRoomJob : public BaseJob { public: @@ -55,16 +63,20 @@ namespace QMatrixClient /// apply the events implied by the request in the following order: /// /// 0. A default ``m.room.power_levels`` event, giving the room creator - /// (and not other members) permission to send state events. + /// (and not other members) permission to send state events. Overridden + /// by the ``power_level_content_override`` parameter. /// - /// 1. Events set by the ``preset``. + /// 1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``, + /// ``m.room.history_visibility``, and ``m.room.guest_access`` state events. /// /// 2. Events listed in ``initial_state``, in the order that they are /// listed. /// - /// 3. Events implied by ``name`` and ``topic``. + /// 3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic`` + /// state events). /// - /// 4. Invite events implied by ``invite`` and ``invite_3pid``. + /// 4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with + /// ``membership: invite`` and ``m.room.third_party_invite``). /// /// The available presets do the following with respect to room state: /// @@ -75,6 +87,10 @@ namespace QMatrixClient /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. /// ``public_chat`` ``public`` ``shared`` ``forbidden`` /// ======================== ============== ====================== ================ ========= + /// + /// The server will create a ``m.room.create`` event in the room with the + /// requesting user as the creator, alongside other keys provided in the + /// ``creation_content``. struct Invite3pid { /// The hostname+port of the identity server which should be used for third party identifier lookups. @@ -92,16 +108,20 @@ namespace QMatrixClient /// apply the events implied by the request in the following order: /// /// 0. A default ``m.room.power_levels`` event, giving the room creator - /// (and not other members) permission to send state events. + /// (and not other members) permission to send state events. Overridden + /// by the ``power_level_content_override`` parameter. /// - /// 1. Events set by the ``preset``. + /// 1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``, + /// ``m.room.history_visibility``, and ``m.room.guest_access`` state events. /// /// 2. Events listed in ``initial_state``, in the order that they are /// listed. /// - /// 3. Events implied by ``name`` and ``topic``. + /// 3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic`` + /// state events). /// - /// 4. Invite events implied by ``invite`` and ``invite_3pid``. + /// 4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with + /// ``membership: invite`` and ``m.room.third_party_invite``). /// /// The available presets do the following with respect to room state: /// @@ -112,6 +132,10 @@ namespace QMatrixClient /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. /// ``public_chat`` ``public`` ``shared`` ``forbidden`` /// ======================== ============== ====================== ================ ========= + /// + /// The server will create a ``m.room.create`` event in the room with the + /// requesting user as the creator, alongside other keys provided in the + /// ``creation_content``. struct StateEvent { /// The type of event to send. @@ -139,6 +163,9 @@ namespace QMatrixClient * created the room. For example, if this was set to "foo" and * sent to the homeserver "example.com" the complete room alias * would be ``#foo:example.com``. + * + * The complete room alias will become the canonical alias for + * the room. * \param name * If this is included, an ``m.room.name`` event will be sent * into the room to indicate the name of the room. See Room @@ -153,11 +180,16 @@ namespace QMatrixClient * \param invite3pid * A list of objects representing third party IDs to invite into * the room. + * \param roomVersion + * The room version to set for the room. If not provided, the homeserver is + * to use its configured default. If provided, the homeserver will return a + * 400 error with the errcode ``M_UNSUPPORTED_ROOM_VERSION`` if it does not + * support the room version. * \param creationContent - * Extra keys to be added to the content of the ``m.room.create``. - * The server will clobber the following keys: ``creator``. Future - * versions of the specification may allow the server to clobber - * other keys. + * Extra keys, such as ``m.federate``, to be added to the content + * of the `m.room.create`_ event. The server will clobber the following + * keys: ``creator``, ``room_version``. Future versions of the specification + * may allow the server to clobber other keys. * \param initialState * A list of state events to set in the new room. This allows * the user to override the default state events set in the new @@ -169,14 +201,22 @@ namespace QMatrixClient * \param preset * Convenience parameter for setting various default state events * based on a preset. + * + * If unspecified, the server should use the ``visibility`` to determine + * which preset to use. A visbility of ``public`` equates to a preset of + * ``public_chat`` and ``private`` visibility equates to a preset of + * ``private_chat``. * \param isDirect * This flag makes the server set the ``is_direct`` flag on the * ``m.room.member`` events sent to the users in ``invite`` and * ``invite_3pid``. See `Direct Messaging`_ for more information. - * \param guestCanJoin - * Allows guests to join the room. See `Guest Access`_ for more information. + * \param powerLevelContentOverride + * The power level content to override in the default power level + * event. This object is applied on top of the generated `m.room.power_levels`_ + * event content prior to it being sent to the room. Defaults to + * overriding nothing. */ - explicit CreateRoomJob(const QString& visibility = {}, const QString& roomAliasName = {}, const QString& name = {}, const QString& topic = {}, const QStringList& invite = {}, const QVector<Invite3pid>& invite3pid = {}, const QJsonObject& creationContent = {}, const QVector<StateEvent>& initialState = {}, const QString& preset = {}, bool isDirect = false, bool guestCanJoin = false); + explicit CreateRoomJob(const QString& visibility = {}, const QString& roomAliasName = {}, const QString& name = {}, const QString& topic = {}, const QStringList& invite = {}, const QVector<Invite3pid>& invite3pid = {}, const QString& roomVersion = {}, const QJsonObject& creationContent = {}, const QVector<StateEvent>& initialState = {}, const QString& preset = {}, bool isDirect = false, const QJsonObject& powerLevelContentOverride = {}); ~CreateRoomJob() override; // Result properties |