Merge branch 'master' of https://github.com/QMatrixClient/libqmatrixclient

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