diff options
Diffstat (limited to 'lib/csapi/create_room.h')
| -rw-r--r-- | lib/csapi/create_room.h | 142 |
1 files changed, 142 insertions, 0 deletions
diff --git a/lib/csapi/create_room.h b/lib/csapi/create_room.h index f7b7e800..ee09fb35 100644 --- a/lib/csapi/create_room.h +++ b/lib/csapi/create_room.h @@ -14,32 +14,174 @@ namespace QMatrixClient { // Operations + /// Create a new room + /// + /// Create a new room with various configuration options. + /// + /// The server MUST apply the normal state resolution rules when creating + /// the new room, including checking power levels for each event. It MUST + /// 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. + /// + /// 1. Events set by the ``preset``. + /// + /// 2. Events listed in ``initial_state``, in the order that they are + /// listed. + /// + /// 3. Events implied by ``name`` and ``topic``. + /// + /// 4. Invite events implied by ``invite`` and ``invite_3pid``. + /// + /// The available presets do the following with respect to room state: + /// + /// ======================== ============== ====================== ================ ========= + /// Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other + /// ======================== ============== ====================== ================ ========= + /// ``private_chat`` ``invite`` ``shared`` ``can_join`` + /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. + /// ``public_chat`` ``public`` ``shared`` ``forbidden`` + /// ======================== ============== ====================== ================ ========= class CreateRoomJob : public BaseJob { public: // Inner data structures + /// Create a new room with various configuration options. + /// + /// The server MUST apply the normal state resolution rules when creating + /// the new room, including checking power levels for each event. It MUST + /// 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. + /// + /// 1. Events set by the ``preset``. + /// + /// 2. Events listed in ``initial_state``, in the order that they are + /// listed. + /// + /// 3. Events implied by ``name`` and ``topic``. + /// + /// 4. Invite events implied by ``invite`` and ``invite_3pid``. + /// + /// The available presets do the following with respect to room state: + /// + /// ======================== ============== ====================== ================ ========= + /// Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other + /// ======================== ============== ====================== ================ ========= + /// ``private_chat`` ``invite`` ``shared`` ``can_join`` + /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. + /// ``public_chat`` ``public`` ``shared`` ``forbidden`` + /// ======================== ============== ====================== ================ ========= struct Invite3pid { + /// The hostname+port of the identity server which should be used for third party identifier lookups. QString idServer; + /// The kind of address being passed in the address field, for example ``email``. QString medium; + /// The invitee's third party identifier. QString address; }; + /// Create a new room with various configuration options. + /// + /// The server MUST apply the normal state resolution rules when creating + /// the new room, including checking power levels for each event. It MUST + /// 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. + /// + /// 1. Events set by the ``preset``. + /// + /// 2. Events listed in ``initial_state``, in the order that they are + /// listed. + /// + /// 3. Events implied by ``name`` and ``topic``. + /// + /// 4. Invite events implied by ``invite`` and ``invite_3pid``. + /// + /// The available presets do the following with respect to room state: + /// + /// ======================== ============== ====================== ================ ========= + /// Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other + /// ======================== ============== ====================== ================ ========= + /// ``private_chat`` ``invite`` ``shared`` ``can_join`` + /// ``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator. + /// ``public_chat`` ``public`` ``shared`` ``forbidden`` + /// ======================== ============== ====================== ================ ========= struct StateEvent { + /// The type of event to send. QString type; + /// The state_key of the state event. Defaults to an empty string. QString stateKey; + /// The content of the event. QJsonObject content; }; // Construction/destruction + /*! Create a new room + * \param visibility + * A ``public`` visibility indicates that the room will be shown + * in the published room list. A ``private`` visibility will hide + * the room from the published room list. Rooms default to + * ``private`` visibility if this key is not included. NB: This + * should not be confused with ``join_rules`` which also uses the + * word ``public``. + * \param roomAliasName + * The desired room alias **local part**. If this is included, a + * room alias will be created and mapped to the newly created + * room. The alias will belong on the *same* homeserver which + * 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``. + * \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 + * Events for more information on ``m.room.name``. + * \param topic + * If this is included, an ``m.room.topic`` event will be sent + * into the room to indicate the topic for the room. See Room + * Events for more information on ``m.room.topic``. + * \param invite + * A list of user IDs to invite to the room. This will tell the + * server to invite everyone in the list to the newly created room. + * \param invite3pid + * A list of objects representing third party IDs to invite into + * the room. + * \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. + * \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 + * room. The expected format of the state events are an object + * with type, state_key and content keys set. + * + * Takes precedence over events set by ``preset``, but gets + * overriden by ``name`` and ``topic`` keys. + * \param preset + * Convenience parameter for setting various default state events + * based on a preset. + * \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. + */ 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); ~CreateRoomJob() override; // Result properties + /// The created room's ID. const QString& roomId() const; protected: |