/******************************************************************************
 * THIS FILE IS GENERATED - ANY EDITS WILL BE OVERWRITTEN
 */

#pragma once

#include "jobs/basejob.h"

namespace QMatrixClient {
    // Operations

    /// Invite a user to participate in a particular room.
    ///
    /// .. _invite-by-third-party-id-endpoint:
    ///
    /// *Note that there are two forms of this API, which are documented
    /// separately. This version of the API does not require that the inviter
    /// know the Matrix identifier of the invitee, and instead relies on third
    /// party identifiers. The homeserver uses an identity server to perform the
    /// mapping from third party identifier to a Matrix identifier. The other is
    /// documented in the* `joining rooms section`_.
    ///
    /// This API invites a user to participate in a particular room.
    /// They do not start participating in the room until they actually join the
    /// room.
    ///
    /// Only users currently in a particular room can invite other users to
    /// join that room.
    ///
    /// If the identity server did know the Matrix user identifier for the
    /// third party identifier, the homeserver will append a ``m.room.member``
    /// event to the room.
    ///
    /// If the identity server does not know a Matrix user identifier for the
    /// passed third party identifier, the homeserver will issue an invitation
    /// which can be accepted upon providing proof of ownership of the third
    /// party identifier. This is achieved by the identity server generating a
    /// token, which it gives to the inviting homeserver. The homeserver will
    /// add an ``m.room.third_party_invite`` event into the graph for the room,
    /// containing that token.
    ///
    /// When the invitee binds the invited third party identifier to a Matrix
    /// user ID, the identity server will give the user a list of pending
    /// invitations, each containing:
    ///
    /// - The room ID to which they were invited
    ///
    /// - The token given to the homeserver
    ///
    /// - A signature of the token, signed with the identity server's private
    /// key
    ///
    /// - The matrix user ID who invited them to the room
    ///
    /// If a token is requested from the identity server, the homeserver will
    /// append a ``m.room.third_party_invite`` event to the room.
    ///
    /// .. _joining rooms section: `invite-by-user-id-endpoint`_
    class InviteBy3PIDJob : public BaseJob
    {
        public:
        /*! Invite a user to participate in a particular room.
         * \param roomId
         *   The room identifier (not alias) to which to invite the user.
         * \param idServer
         *   The hostname+port of the identity server which should be used for
         * third party identifier lookups. \param medium The kind of address
         * being passed in the address field, for example ``email``. \param
         * address The invitee's third party identifier.
         */
        explicit InviteBy3PIDJob(const QString& roomId, const QString& idServer,
                                 const QString& medium, const QString& address);
    };
} // namespace QMatrixClient