Class CarbonManager


  • public final class CarbonManager
    extends org.jivesoftware.smack.Manager
    Manager for XEP-0280: Message Carbons. This class implements the manager for registering CarbonExtension support, enabling and disabling message carbons, and for CarbonCopyReceivedListener.

    Note that it is important to match the 'from' attribute of the message wrapping a carbon copy, as otherwise it would may be possible for others to impersonate users. Smack's CarbonManager takes care of that in CarbonCopyReceivedListeners which were registered with addCarbonCopyReceivedListener(CarbonCopyReceivedListener).

    You should call enableCarbons() before sending your first undirected presence (aka. the "initial presence").

    • Method Detail

      • setEnabledByDefault

        public static void setEnabledByDefault​(boolean enabledByDefault)
        Should Carbons be automatically be enabled once the connection is authenticated? Default: false
        Parameters:
        enabledByDefault - new default value
      • getInstanceFor

        public static CarbonManager getInstanceFor​(org.jivesoftware.smack.XMPPConnection connection)
        Obtain the CarbonManager responsible for a connection.
        Parameters:
        connection - the connection object.
        Returns:
        a CarbonManager instance
      • addCarbonCopyReceivedListener

        public boolean addCarbonCopyReceivedListener​(CarbonCopyReceivedListener listener)
        Add a carbon copy received listener.
        Parameters:
        listener - the listener to register.
        Returns:
        true if the filter was not already registered.
        Since:
        4.2
      • removeCarbonCopyReceivedListener

        public boolean removeCarbonCopyReceivedListener​(CarbonCopyReceivedListener listener)
        Remove a carbon copy received listener.
        Parameters:
        listener - the listener to register.
        Returns:
        true if the filter was registered.
        Since:
        4.2
      • isSupportedByServer

        public boolean isSupportedByServer()
                                    throws org.jivesoftware.smack.SmackException.NoResponseException,
                                           org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                           org.jivesoftware.smack.SmackException.NotConnectedException,
                                           java.lang.InterruptedException
        Returns true if XMPP Carbons are supported by the server.
        Returns:
        true if supported
        Throws:
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        java.lang.InterruptedException - if the calling thread was interrupted.
      • sendCarbonsEnabled

        @Deprecated
        public void sendCarbonsEnabled​(boolean new_state)
        Notify server to change the carbons state. This method returns immediately and changes the variable when the reply arrives. You should first check for support using isSupportedByServer().
        Parameters:
        new_state - whether carbons should be enabled or disabled
      • enableCarbonsAsync

        public void enableCarbonsAsync​(org.jivesoftware.smack.util.ExceptionCallback<java.lang.Exception> exceptionCallback)
        Enable carbons asynchronously. If an error occurs as result of the attempt to enable carbons, the optional exceptionCallback will be invoked.

        Note that although this method is asynchronous, it may block if the outgoing stream element queue is full (e.g. because of a slow network connection). Thus, if the thread performing this operation is interrupted while the queue is full, an InterruptedException is thrown.

        Parameters:
        exceptionCallback - the optional exception callback.
        Since:
        4.2
      • disableCarbonsAsync

        public void disableCarbonsAsync​(org.jivesoftware.smack.util.ExceptionCallback<java.lang.Exception> exceptionCallback)
        Disable carbons asynchronously. If an error occurs as result of the attempt to disable carbons, the optional exceptionCallback will be invoked.

        Note that although this method is asynchronous, it may block if the outgoing stream element queue is full (e.g. because of a slow network connection). Thus, if the thread performing this operation is interrupted while the queue is full, an InterruptedException is thrown.

        Parameters:
        exceptionCallback - the optional exception callback.
        Since:
        4.2
      • setCarbonsEnabled

        public void setCarbonsEnabled​(boolean new_state)
                               throws org.jivesoftware.smack.SmackException.NoResponseException,
                                      org.jivesoftware.smack.XMPPException.XMPPErrorException,
                                      org.jivesoftware.smack.SmackException.NotConnectedException,
                                      java.lang.InterruptedException
        Notify server to change the carbons state. This method blocks some time until the server replies to the IQ and returns true on success. You should first check for support using isSupportedByServer().
        Parameters:
        new_state - whether carbons should be enabled or disabled
        Throws:
        org.jivesoftware.smack.XMPPException.XMPPErrorException - if there was an XMPP error returned.
        org.jivesoftware.smack.SmackException.NoResponseException - if there was no response from the remote entity.
        org.jivesoftware.smack.SmackException.NotConnectedException - if the XMPP connection is not connected.
        java.lang.InterruptedException - if the calling thread was interrupted.
      • enableCarbons

        public void enableCarbons()
                           throws org.jivesoftware.smack.XMPPException,
                                  org.jivesoftware.smack.SmackException,
                                  java.lang.InterruptedException
        Helper method to enable carbons.
        Throws:
        org.jivesoftware.smack.XMPPException - if an XMPP protocol error was received.
        org.jivesoftware.smack.SmackException - if there was no response from the server.
        java.lang.InterruptedException - if the calling thread was interrupted.
      • disableCarbons

        public void disableCarbons()
                            throws org.jivesoftware.smack.XMPPException,
                                   org.jivesoftware.smack.SmackException,
                                   java.lang.InterruptedException
        Helper method to disable carbons.
        Throws:
        org.jivesoftware.smack.XMPPException - if an XMPP protocol error was received.
        org.jivesoftware.smack.SmackException - if there was no response from the server.
        java.lang.InterruptedException - if the calling thread was interrupted.
      • getCarbonsEnabled

        public boolean getCarbonsEnabled()
        Check if carbons are enabled on this connection.
        Returns:
        true if carbons are enabled, else false.
      • disableCarbons

        @Deprecated
        public static void disableCarbons​(org.jivesoftware.smack.packet.Message msg)
        Mark a message as "private", so it will not be carbon-copied.
        Parameters:
        msg - Message object to mark private