QXmppMucRoomV2 Class

auto canSend = room.canSendMessages();
canSend.addNotifier([canSend]() {
    qDebug() << "canSendMessages changed:" << canSend.value();
});

Member Function Documentation

[delete] QXmppMucRoomV2::QXmppMucRoomV2()

Default-constructs an instance of QXmppMucRoomV2. This function is deleted.

[noexcept default] QXmppMucRoomV2::QXmppMucRoomV2(const QXmppMucRoomV2 &)

Copy-constructs an instance of QXmppMucRoomV2.

[noexcept default] QXmppMucRoomV2::QXmppMucRoomV2(QXmppMucRoomV2 &&)

Move-constructs an instance of QXmppMucRoomV2.

[since QXmpp 1.16] QXmppTask<QXmpp::SendResult> QXmppMucRoomV2::answerVoiceRequest(const QXmppMucVoiceRequest &request, bool allow)

Approves or denies a voice request as a moderator.

Sends the request form back to the room with muc#request_allow set to allow. If allow is true the MUC service promotes the visitor to participant; if false the request is denied and the visitor remains a visitor.

The returned task reflects the stream-management acknowledgement: QXmpp::SendSuccess::acknowledged is true once the server has confirmed receipt. Returns an error task immediately if the room is not currently joined.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QBindable<std::optional<QXmpp::Muc::Avatar>> QXmppMucRoomV2::avatar() const

Returns the cached room avatar.

Populated after setWatchAvatar(true) has been called and the vcard-temp fetch has completed. Automatically re-fetched whenever a status code 104 (room configuration changed) causes the avatar hashes to change.

Returns std::nullopt until the first fetch completes, or if the room has no avatar or the MUC service does not support vcard-temp.

This function was introduced in QXmpp 1.16.

See also setAvatar(), avatarHashes(), and setWatchAvatar().

[since QXmpp 1.16] QBindable<QStringList> QXmppMucRoomV2::avatarHashes() const

Returns the avatar hashes for the room from XEP-0045: Multi-User Chat muc#roominfo.

The hashes are derived from the muc#roominfo_avatarhash field of the disco\#info response. They are automatically updated on join and whenever a status code 104 (room configuration changed) is received.

Returns an empty list until the first disco\#info response has arrived or if no avatar has been published.

This function was introduced in QXmpp 1.16.

See also avatar() and setWatchAvatar().

QBindable<bool> QXmppMucRoomV2::canChangeSubject() const

Returns whether the local user can change the room subject.

True for Moderators, or for Participants when the room allows it (muc#roominfo_subjectmod). Defaults to false until disco#info arrives.

QBindable<bool> QXmppMucRoomV2::canConfigureRoom() const

Returns whether the local user can configure the room (XEP-0045 §10).

True when the user's affiliation is Owner.

QBindable<bool> QXmppMucRoomV2::canModerateMessages() const

Returns whether the local user can moderate (retract) messages in this room (XEP-0425: Moderated Message Retraction).

True when the room advertises support for moderated retraction and the user's role is Moderator.

QBindable<bool> QXmppMucRoomV2::canSendMessages() const

Returns whether the local user can send groupchat messages.

True when the user's role is Participant or Moderator. In unmoderated rooms the server assigns Participant by default.

QBindable<bool> QXmppMucRoomV2::canSetAffiliations() const

Returns whether the local user can change affiliations (XEP-0045 §9).

True when the user's affiliation is Admin or Owner. This covers banning, granting and revoking membership, and querying affiliation lists.

QBindable<bool> QXmppMucRoomV2::canSetRoles() const

Returns whether the local user can change other participants' roles (XEP-0045 §8.4–8.6).

True when the user's role is Moderator. This covers role changes including kicking (setting role to None) and granting/revoking voice.

[since QXmpp 1.16] QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::cancelRoomCreation()

Cancels room creation and destroys the locked room on the server.

Only valid in the Creating state (i.e. after createRoom() has resolved but before setRoomConfig() has been called). Sending the cancel form instructs the server to destroy the still-locked room.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QBindable<QStringList> QXmppMucRoomV2::contactJids() const

Returns the list of admin contact JIDs for the room from XEP-0045: Multi-User Chat muc#roominfo.

The JIDs are populated from the muc#roominfo_contactjid field of the disco\#info response. They represent real JIDs of people responsible for the room, which may differ from the room's current affiliations list. The list is fetched automatically on join and re-fetched whenever a status code 104 is received.

Returns an empty list until the disco\#info response has arrived or if the room has no contact JIDs configured.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QBindable<QString> QXmppMucRoomV2::description() const

The description is populated from the muc#roominfo_description field of the disco\#info response. It is fetched automatically on join and re-fetched whenever a status code 104 (room configuration changed) is received.

Returns an empty string until the disco\#info response has arrived.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::destroyRoom(const QString &reason = {}, const QString &alternateJid = {})

Destroys the MUC room on the server.

Only valid in the Joined state. Sends a destroy IQ to the MUC service. An optional reason and an alternateJid can be provided; the alternate JID is sent to occupants so they may join an alternative room.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QXmppTask<QXmpp::SendResult> QXmppMucRoomV2::inviteUser(QXmpp::Muc::Invite invite)

Sends the mediated invite via this room.

The room must be currently joined. The room service will forward the invitation to the specified invitee and add the room password automatically for password-protected rooms.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QBindable<bool> QXmppMucRoomV2::isMembersOnly() const

Returns whether the room is members-only (XEP-0045 §4.2).

In a members-only room (muc_membersonly), users must be on the member list to enter. Open rooms (muc_open) allow any non-banned user to join.

Populated from the muc_membersonly disco feature on join and re-fetched on status code 104.

Defaults to false until disco#info arrives.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QBindable<bool> QXmppMucRoomV2::isModerated() const

Returns whether the room is moderated (XEP-0045 §4.2).

In a moderated room (muc_moderated), only occupants with voice (role Participant or Moderator) can send messages. Visitors cannot.

Populated from the muc_moderated disco feature on join and re-fetched on status code 104.

Defaults to false until disco#info arrives.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QBindable<bool> QXmppMucRoomV2::isNonAnonymous() const

Returns whether the room is non-anonymous (XEP-0045 §4.2).

In a non-anonymous room, all occupants can see each other's real JIDs. In a semi-anonymous room (the default), only moderators can see real JIDs.

Populated from the muc_nonanonymous disco feature on join and re-fetched on status code 104. Also updated immediately on status codes 172 (now non-anonymous) and 173 (now semi-anonymous), without a round-trip.

Defaults to false (semi-anonymous) until disco#info arrives.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QBindable<bool> QXmppMucRoomV2::isPasswordProtected() const

Returns whether the room requires a password to enter (XEP-0045 §4.2).

Password-protected rooms (muc_passwordprotected) require the correct password when joining (XEP-0045 §7.2.5).

Populated from the muc_passwordprotected disco feature on join and re-fetched on status code 104.

Defaults to false until disco#info arrives.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QBindable<bool> QXmppMucRoomV2::isPersistent() const

Returns whether the room is persistent (XEP-0045 §4.2).

A persistent room (muc_persistent) is not destroyed when the last occupant exits. A temporary room (muc_temporary) is destroyed automatically.

Populated from the muc_persistent disco feature on join and re-fetched on status code 104.

Defaults to false until disco#info arrives.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QBindable<bool> QXmppMucRoomV2::isPublic() const

Returns whether the room is publicly listed (XEP-0045 §4.2).

Public rooms (muc_public) appear in service discovery results. Hidden rooms (muc_hidden) do not.

Populated from the muc_public disco feature on join and re-fetched on status code 104.

Defaults to true until disco#info arrives.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] bool QXmppMucRoomV2::isWatchingAvatar() const

Returns whether automatic avatar updates are enabled.

This function was introduced in QXmpp 1.16.

See also setWatchAvatar().

[since QXmpp 1.16] bool QXmppMucRoomV2::isWatchingRoomConfig() const

Returns whether automatic room configuration updates are enabled.

This function was introduced in QXmpp 1.16.

See also setWatchRoomConfig().

QString QXmppMucRoomV2::jid() const

Returns the room JID this handle refers to.

QBindable<bool> QXmppMucRoomV2::joined() const

Returns whether the room is currently joined as a bindable property.

[since QXmpp 1.16] QBindable<QString> QXmppMucRoomV2::language() const

Returns the language of the room discussion from XEP-0045: Multi-User Chat muc#roominfo.

The language tag is populated from the muc#roominfo_lang field of the disco\#info response, following BCP 47 (e.g. "en" or "de"). It is fetched automatically on join and re-fetched whenever a status code 104 is received.

Returns an empty string until the disco\#info response has arrived.

This function was introduced in QXmpp 1.16.

QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::leave()

Leaves the room by sending an unavailable presence (XEP-0045 §7.14).

The returned task completes when the server confirms the leave with a self-unavailable presence containing status code 110.

QXmppMucManagerV2 *QXmppMucRoomV2::manager() const

Returns the manager that owns this room's state.

QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::moderateMessage(const QString &stanzaId, const QString &reason = {})

Retracts the message with XEP-0359: stanza id stanzaId from this room as a moderator, optionally providing a reason (XEP-0425: Moderated Message Retraction).

Requires the Moderator role and room support; see canModerateMessages().

QBindable<QString> QXmppMucRoomV2::nickname() const

Returns the user's nickname in the room as a bindable property.

See also setNickname().

template <typename Func> QMetaObject::Connection QXmppMucRoomV2::onParticipantJoined(QObject *context, Func &&f) const

Connects f to the participantJoined signal, filtered for this room, with the given context object.

template <typename Func> QMetaObject::Connection QXmppMucRoomV2::onParticipantLeft(QObject *context, Func &&f) const

Connects f to the participantLeft signal, filtered for this room, with the given context object.

QList<QXmppMucParticipant> QXmppMucRoomV2::participants() const

Returns a list of all participants currently in the room.

The returned handles are lightweight and do not own any data.

QXmppTask<QXmpp::Result<QList<QXmpp::Muc::Item>>> QXmppMucRoomV2::requestAffiliationList(QXmpp::Muc::Affiliation affiliation)

Requests the list of all users with a given affiliation (XEP-0045 §9.5–9.8).

Returns a snapshot of the affiliation list. There are no live updates; call this method again after making changes if you need a fresh list.

Only admins and owners are allowed to retrieve these lists.

QXmppTask<QXmpp::Result<QXmppDataForm>> QXmppMucRoomV2::requestRegistrationForm()

Requests the registration form for this room (XEP-0045 §7.10).

Returns the data form that needs to be filled in and submitted via submitRegistration().

QXmppTask<QXmpp::Result<QString>> QXmppMucRoomV2::requestReservedNickname()

Queries the server for the user's reserved nickname in this room (XEP-0045 §7.12).

Returns the reserved nickname, or an empty string if no nickname is reserved.

[since QXmpp 1.16] QXmppTask<QXmpp::Result<QXmppMucRoomConfig>> QXmppMucRoomV2::requestRoomConfig(bool watch = false)

Requests the current room configuration form from the server.

Valid in both the Creating and Joined states. Returns a QXmppMucRoomConfig that can be edited and submitted via setRoomConfig(). Also updates the roomConfig() bindable on success.

If watching is active (setWatchRoomConfig(true) or watch = true) and the configuration has already been fetched, the cached value is returned immediately without a network request. When watching is disabled the cached value may be stale, so a fresh fetch is always performed in that case.

If watch is true, enables automatic re-fetching on status code 104 (room configuration changed). Equivalent to calling setWatchRoomConfig(true) before this call.

This function was introduced in QXmpp 1.16.

See also setRoomConfig(), roomConfig(), and setWatchRoomConfig().

[since QXmpp 1.16] QXmppTask<QXmpp::SendResult> QXmppMucRoomV2::requestVoice()

Requests voice in a moderated room as a visitor.

Sends a muc#request data form to the room. The MUC service forwards an approval form to all moderators, who can then call answerVoiceRequest() to grant or deny voice.

The returned task reflects the stream-management acknowledgement: QXmpp::SendSuccess::acknowledged is true once the server has confirmed receipt. Returns an error task immediately if the room is not currently joined.

This function was introduced in QXmpp 1.16.

[since QXmpp 1.16] QBindable<std::optional<QXmppMucRoomConfig>> QXmppMucRoomV2::roomConfig() const

Returns the current room configuration form from XEP-0045: Multi-User Chat.

The form is populated after requestRoomConfig() or setWatchRoomConfig(true) has been called and the initial fetch has completed. While watching is active, the form is automatically re-fetched whenever a status code 104 (room configuration changed) is received.

Returns std::nullopt until the first response has arrived.

This function was introduced in QXmpp 1.16.

See also setRoomConfig(), requestRoomConfig(), and setWatchRoomConfig().

[since QXmpp 1.16] QBindable<std::optional<QXmppMucRoomInfo>> QXmppMucRoomV2::roomInfo() const

Returns the full muc#roominfo data form from XEP-0045: Multi-User Chat.

The form is fetched via disco\#info automatically on join and re-fetched whenever a status code 104 (room configuration changed) is received. It gives access to all available room info fields in one object, including fields not individually exposed (e.g. muc#roominfo_subject, muc#roominfo_occupants, muc#roominfo_avatarhash).

Returns std::nullopt until the first disco\#info response has arrived or if the room's disco#info does not include a muc#roominfo form.

This function was introduced in QXmpp 1.16.

See also description(), language(), and contactJids().

std::optional<QXmppMucParticipant> QXmppMucRoomV2::selfParticipant() const

Returns a handle to the local user's own participant entry, if joined.

Returns std::nullopt before joinRoom() has completed or after leaving the room. Use the returned handle's role() and affiliation() QBindables to reactively observe your own permissions — they update automatically when the MUC service grants or revokes permissions.

QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::sendMessage(QXmppMessage message)

Sends the groupchat message to the room.

The message's to and type fields are set automatically. An origin-id (XEP-0359: Unique and Stable Stanza IDs) is generated if not already set, and is used to match the server's reflected message.

The returned task completes with success when the message is reflected back by the MUC service, or with an error if the service responds with an error or the request times out.

QXmppTask<QXmpp::SendResult> QXmppMucRoomV2::sendPrivateMessage(const QXmppMucParticipant &participant, QXmppMessage message)

Sends the private message to a room participant.

The message is addressed to the occupant's current room JID (room@service/nick). The returned task completes when the message has been sent to the server.

QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::setAffiliation(const QString &jid, QXmpp::Muc::Affiliation affiliation, const QString &reason = {})

Changes the affiliation of a user by bare jid for the given reason (XEP-0045 §9).

Affiliation changes are persistent. The jid must be a bare JID. The user does not need to be currently in the room.

QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::setAffiliations(const QList<QXmpp::Muc::Item> &items)

Changes the affiliations of multiple users in a single request (XEP-0045 §9), described by items.

Each item must have its jid and affiliation set. Affiliation changes are persistent and the users do not need to be currently in the room.

[since QXmpp 1.16] QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::setAvatar(std::optional<QXmpp::Muc::Avatar> newAvatar)

Sets or removes the avatar of the room via vcard-temp.

Pass newAvatar to publish a new avatar, or std::nullopt to remove the current one.

Requires the MUC service to support "vcard-temp" and the local user to be an owner or other privileged entity of the room.

This function was introduced in QXmpp 1.16.

See also avatar().

QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::setNickname(const QString &newNick)

Changes the user's nickname in the room to newNick.

Sends a presence to the new occupant JID. The returned task completes when the MUC service confirms the change (status code 303), or with an error if it is rejected.

See also nickname().

QXmppTask<QXmpp::SendResult> QXmppMucRoomV2::setPresence(QXmppPresence presence)

Changes the user's presence in the room.

The presence is addressed to the user's current occupant JID. The returned task completes when the presence has been sent to the server.

QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::setRole(const QXmppMucParticipant &participant, QXmpp::Muc::Role role, const QString &reason = {})

Changes the role of a room participant for the given reason (XEP-0045 §8.4–8.6).

Role changes are transient and apply only for the current session. The participant must still be in the room. Roles are identified by the participant's current nickname.

QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::setRoles(const QList<QXmpp::Muc::Item> &items)

Changes the roles of multiple room participants in a single request (XEP-0045 §8.5), described by items.

Each item must have its nick and role set. Role changes are transient and apply only for the current session.

[since QXmpp 1.16] QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::setRoomConfig(const QXmppMucRoomConfig &config)

Submits the room config to the server.

In the Creating state (after createRoom()) this unlocks the room and transitions it to the Joined state. In the Joined state this updates an existing room's configuration.

This function was introduced in QXmpp 1.16.

See also roomConfig().

QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::setSubject(const QString &subject)

Changes the room subject to subject.

Sends a subject-only groupchat message. The returned task completes when the MUC service reflects the subject change, or with an error if the service rejects it or the request times out.

See also subject().

[since QXmpp 1.16] void QXmppMucRoomV2::setWatchAvatar(bool watch)

Enables or disables automatic avatar updates based on watch.

When set to true, the avatar is fetched immediately if the room info is already available and the hashes have not been fetched yet. Whenever a status code 104 (room configuration changed) causes the avatar hashes to change, the avatar is re-fetched automatically.

When set to false, auto-refresh is disabled. The last fetched avatar remains available in avatar() but is no longer updated automatically.

This function was introduced in QXmpp 1.16.

See also avatar() and avatarHashes().

[since QXmpp 1.16] void QXmppMucRoomV2::setWatchRoomConfig(bool watch)

Enables or disables automatic room configuration updates based on watch.

When set to true, status code 104 messages (room configuration changed) will automatically trigger a re-fetch to keep roomConfig() current. If the configuration has not been fetched yet, a fetch is triggered immediately (fire-and-forget; use requestRoomConfig() if you need the result).

When set to false, disables auto-refresh. The last fetched configuration remains available in roomConfig() but is no longer updated automatically.

This function was introduced in QXmpp 1.16.

See also roomConfig() and requestRoomConfig().

QBindable<QString> QXmppMucRoomV2::subject() const

Returns the room subject as a bindable property.

See also setSubject().

QXmppTask<QXmpp::Result<>> QXmppMucRoomV2::submitRegistration(const QXmppDataForm &form)

Submits a filled-in registration form to the room (XEP-0045 §7.10).

The form should be the form returned by requestRegistrationForm(), filled in by the user, with its type set to QXmppDataForm::Submit.

[noexcept default] QXmppMucRoomV2 &QXmppMucRoomV2::operator=(QXmppMucRoomV2 &&)

Move-assigns other to this QXmppMucRoomV2 instance.

[noexcept default] QXmppMucRoomV2 &QXmppMucRoomV2::operator=(const QXmppMucRoomV2 &)

Copy-assigns other to this QXmppMucRoomV2 instance.