Package org.jivesoftware.smackx.carbons

Class CarbonManager

java.lang.Object
org.jivesoftware.smack.Manager
org.jivesoftware.smackx.carbons.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 Details

    • 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, 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.
      InterruptedException - if the calling thread was interrupted.

    • sendCarbonsEnabled

      @Deprecated public void sendCarbonsEnabled(boolean new_state)
      Deprecated.
      use enableCarbonsAsync(ExceptionCallback) or disableCarbonsAsync(ExceptionCallback) instead.
      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<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<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, 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.
      InterruptedException - if the calling thread was interrupted.

    • enableCarbons

      public void enableCarbons() throws org.jivesoftware.smack.XMPPException, org.jivesoftware.smack.SmackException, 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.
      InterruptedException - if the calling thread was interrupted.

    • disableCarbons

      public void disableCarbons() throws org.jivesoftware.smack.XMPPException, org.jivesoftware.smack.SmackException, 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.
      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)
      Deprecated.
      use CarbonExtension.Private.addTo(Message)
      Mark a message as "private", so it will not be carbon-copied.
      Parameters:
      msg - Message object to mark private