mucroom.h

Jabber code library, developed with c

      /**
       * Use this function to request room history. Set @c value to zero to disable the room
       * history request. You should not use HistorySince type with this function.
       * History is sent only once after entering a room. You should use this function before joining.
       * @param value Represents either the number of requested characters, the number of requested
       * message stanzas, or the number seconds, depending on the value of @c type.
       * @param type
       * @note If this function is not used to request a specific amount of room history, it is up
       * to the MUC service to decide how much history to send.
       */
      void setRequestHistory( int value, HistoryRequestType type );

      /**
       * Use this function to request room history since specific datetime.
       * History is sent only once after entering a room. You should use this function before joining.
       * @param since A string representing a datetime conforming to the DateTime profile specified
       * in Jabber Date and Time Profiles (XEP-0082).
       * @note If this function is not used to request a specific amount of room history, it is up
       * to the MUC service to decide how much history to send.
       */
      void setRequestHistory( const std::string& since );

      /**
       * This static function allows to formally decline a MUC invitation received via the
       * MUCInvitationListener.
       * @param room The JID of the room the invitation came from.
       * @param invitor The JID of the invitor.
       * @param reason An optional reason for the decline.
       */
      static Stanza* declineInvitation( const JID& room, const JID& invitor,
                                        const std::string& reason = "");

      /**
       * It is not possible for a visitor to speak in a moderated room. Use this function to request
       * voice from the moderator.
       */
      void requestVoice();

      /**
       * Use this function to kick a user from the room.
       * Depending on service and/or room configuration and role/affiliation
       * this may not always succeed. Usually, a role of 'moderator' is necessary.
       * @note This is a convenience function. It directly uses setRole() with a MUCRoomRole of RoleNone.
       * @param nick The nick of the user to be kicked.
       * @param reason An optional reason for the kick.
       */
      void kick( const std::string& nick, const std::string& reason = "" );

      /**
       * Use this function to ban a user from the room.
       * Depending on service and/or room configuration and role/affiliation
       * this may not always succeed. Usually, an affiliation of admin is necessary.
       * @note This is a convenience function. It directly uses setAffiliation() with a MUCRoomAffiliation
       * of RoleOutcast.
       * @param nick The nick of the user to be banned.
       * @param reason An optional reason for the ban.
       */
      void ban( const std::string& nick, const std::string& reason );

      /**
       * Use this function to grant voice to a user in a moderated room.
       * Depending on service and/or room configuration and role/affiliation
       * this may not always succeed. Usually, a role of 'moderator' is necessary.
       * @note This is a convenience function. It directly uses setRole() with a MUCRoomRole
       * of RoleParticipant.
       * @param nick The nick of the user to be granted voice.
       * @param reason An optional reason for the grant.
       */
      void grantVoice( const std::string& nick, const std::string& reason );

      /**
       * Use this function to create a Tag that approves a voice request or registration request
       * delivered via MUCRoomConfigHandler::handleMUCVoiceRequest(). You will need to send this
       * Tag off manually using Client/ClientBase.
       * @param room The room's JID. This is needed because you can use this function outside of
       * room context (e.g, if the admin is not in the room).
       * @param df The filled-in DataForm from the voice/registration request.
       */
      static Stanza* createDataForm( const JID& room, const DataForm& df );

      /**
       * Use this function to revoke voice from a user in a moderated room.
       * Depending on service and/or room configuration and role/affiliation
       * this may not always succeed. Usually, a role of 'moderator' is necessary.
       * @note This is a convenience function. It directly uses setRole() with a MUCRoomRole
       * of RoleVisitor.
       * @param nick The nick of the user.
       * @param reason An optional reason for the revoke.
       */
      void revokeVoice( const std::string& nick, const std::string& reason );

      /**
       * Use this function to change the role of a user in the room.
       * Usually, at least moderator privileges are required to succeed.
       * @param nick The nick of the user who's role shall be modfified.
       * @param role The user's new role in the room.
       * @param reason An optional reason for the role change.
       */
      void setRole( const std::string& nick, MUCRoomRole role, const std::string& reason = "" );

      /**
       * Use this function to change the affiliation of a user in the room.
       * Usually, at least admin privileges are required to succeed.
       * @param nick The nick of the user who's affiliation shall be modfified.
       * @param affiliation The user's new affiliation in the room.
       * @param reason An optional reason for the affiliation change.
       */
      void setAffiliation( const std::string& nick, MUCRoomAffiliation affiliation,
                           const std::string& reason );

      /**
       * Use this function to request the room's configuration form.
       * It can be used either after MUCRoomHandler::handleMUCRoomCreation() was called,
       * or at any later time.
       *
       * Usually owner privileges are required for this action to succeed.
       */
      void requestRoomConfig();

      /**
       * Use this function to accept the room's default configuration. This function is useful
       * only after MUCRoomHandler::handleMUCRoomCreation() was called. This is a NOOP at
       * any other time.
       */
      void acknowledgeInstantRoom();

      /**
       * Use this function to cancel the creation of a room. This function is useful only after
       * MUCRoomHandler::handleMUCRoomCreation() was called. This is a NOOP at any other time.
       */
      void cancelRoomCreation();

      /**
       * Use this function to destroy the room. All the occupants will be removed from the room.
       * @param reason An optional reason for the destruction.
       * @param alternate A pointer to a JID of an alternate venue (e.g., another MUC room).
       * May be 0.
       * @param password An optional password for the alternate venue.
       *
       * Usually owner privileges are required for this action to succeed.
       */
      void destroy( const std::string& reason = "",
                    const JID* alternate = 0, const std::string& password = "" );

      /**
       * Use this function to request a particluar list of room occupants.
       * @note There must be a MUCRoomConfigHandler registered with this room for this
       * function to be executed.
       * @param operation The following types of lists are available:
       * @li Voice List: List of people having voice in a moderated room. Use RequestVoiceList.
       * @li Members List: List of members of a room. Use RequestMemberList.
       * @li Ban List: List of people banned from the room. Use RequestBanList.
       * @li Moderator List: List of room moderators. Use RequestModeratorList.
       * @li Admin List: List of room admins. Use RequestAdminList.
       * @li Owner List: List of room owners. Use RequestOwnerList.
       * Any other value of @c operation will be ignored.
       */
      void requestList( MUCOperation operation );

      /**
       * Use this function to store a (modified) list for the room.
       * @param items The list of items. Example:<br>
       * You want to set the Voice List. The privilege of Voice refers to the role of Participant.
       * Furthermore, you only store the delta of the original (Voice)List. (Optionally, you could
       * probably store the whole list, however, remeber to include those items that were modified,
       * too.)
       * You want to, say, add one occupant to the Voice List, and remove another one.
       * Therefore you store:
       * @li GuyOne, role participant -- this guy gets voice granted, he/she is now a participant.
       * @li GuyTwo, role visitor -- this guy gets voice revoked, he/she is now a mere visitor
       * (Visitor is the Role "below" Participant in the privileges hierarchy).
       *
       * For operations modifying Roles, you should specifiy only the new Role in the MUCListItem
       * structure, for those modifying Affiliations, you should only specify the new Affiliation,
       * respectively. The nickname is mandatory in the MUCListItem structure. Items without nickname
       * will be ignored.
       *
       * You may specify a reason for the role/affiliation change in the MUCListItem structure.
       * You should not specify a JID in the MUCListItem structure, it will be ignored.
       *
       * @param operation See requestList() for a list of available list types. Any other value will
       * be ignored.
       */
      void storeList( const MUCListItemList items, MUCOperation operation );

      /**
       * Returns the currently know room flags.
       * @return ORed MUCRoomFlag's describing the current room configuration.
       */
      int flags() const { return m_flags; }

      // reimplemented from DiscoHandler
      virtual void handleDiscoInfoResult( Stanza *stanza, int context );

      // reimplemented from DiscoHandler
      virtual void handleDiscoItemsResult( Stanza *stanza, int context );

      // reimplemented from DiscoHandler
      virtual void handleDiscoError( Stanza *stanza, int context );

      // reimplemented from PresenceHandler
      virtual void handlePresence( Stanza *stanza );

      // reimplemented from MessageHandler
      virtual void handleMessage( Stanza *stanza, MessageSession *session = 0 );

      // reimplemented from IqHandler
      virtual bool handleIq( Stanza* /*stanza*/ ) { return false; }

      // reimplemented from IqHandler
      virtual bool handleIqID( Stanza *stanza, int context );

      // reimplemented from DiscoNodeHandler
      virtual StringList handleDiscoNodeFeatures( const std::string& node );

      // reimplemented from DiscoNodeHandler
      virtual StringMap handleDiscoNodeIdentities( const std::string& node, std::string& name );

      // reimplemented from DiscoNodeHandler
      virtual DiscoNodeItemList handleDiscoNodeItems( const std::string& node = "" );

    protected:
      void setName( const std::string& name ) { m_nick.setUsername( name ); }
      virtual bool instantRoomHook() const { return false; }

      ClientBase *m_parent;
      JID m_nick;

      bool m_joined;

    private:
      bool handleIqResult( Stanza *stanza, int context );
      bool handleIqError( Stanza *stanza, int context );
      void setNonAnonymous();
      void setSemiAnonymous();
      void setFullyAnonymous();
      void modifyOccupant( const std::string& nick, int state, const std::string roa,
                           const std::string& reason );
      void acknowledgeRoomCreation();
      MUCRoomAffiliation getEnumAffiliation( const std::string& affiliation );
      MUCRoomRole getEnumRole( const std::string& role );

      MUCRoomHandler *m_roomHandler;
      MUCRoomConfigHandler *m_roomConfigHandler;
      MUCMessageSession *m_session;

      typedef std::list<MUCRoomParticipant> ParticipantList;
      ParticipantList m_participants;

      std::string m_password;
      std::string m_newNick;

      MUCRoomAffiliation m_affiliation;
      MUCRoomRole m_role;

      HistoryRequestType m_historyType;

      std::string m_historySince;
      int m_historyValue;
      int m_flags;
      bool m_creationInProgress;
      bool m_configChanged;
      bool m_publishNick;
      bool m_publish;
      bool m_unique;

  };

}

#endif // MUCROOM_H__