org.jivesoftware.smackx.carbons

Class CarbonManager

java.lang.Object

org.jivesoftware.smack.Manager

org.jivesoftware.smackx.carbons.CarbonManager

public final class CarbonManager
extends 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 where registered with addCarbonCopyReceivedListener(CarbonCopyReceivedListener).

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

Method Summary

Modifier and Type	Method and Description
boolean	addCarbonCopyReceivedListener(CarbonCopyReceivedListener listener) Add a carbon copy received listener.
void	disableCarbons() Helper method to disable carbons.
static void	disableCarbons(Message msg) Deprecated. use CarbonExtension.Private.addTo(Message)
void	disableCarbonsAsync(ExceptionCallback<Exception> exceptionCallback) Disable carbons asynchronously.
void	enableCarbons() Helper method to enable carbons.
void	enableCarbonsAsync(ExceptionCallback<Exception> exceptionCallback) Enable carbons asynchronously.
boolean	getCarbonsEnabled() Check if carbons are enabled on this connection.
static CarbonManager	getInstanceFor(XMPPConnection connection) Obtain the CarbonManager responsible for a connection.
boolean	isSupportedByServer() Returns true if XMPP Carbons are supported by the server.
boolean	removeCarbonCopyReceivedListener(CarbonCopyReceivedListener listener) Remove a carbon copy received listener.
void	sendCarbonsEnabled(boolean new_state) Deprecated. use enableCarbonsAsync(ExceptionCallback) or disableCarbonsAsync(ExceptionCallback) instead.
void	setCarbonsEnabled(boolean new_state) Notify server to change the carbons state.

Methods inherited from class org.jivesoftware.smack.Manager

connection, getAuthenticatedConnectionOrThrow, schedule

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstanceFor

public static CarbonManager getInstanceFor(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 SmackException.NoResponseException,
                                   XMPPException.XMPPErrorException,
                                   SmackException.NotConnectedException,
                                   InterruptedException

Returns true if XMPP Carbons are supported by the server.

Returns:

true if supported

Throws:

SmackException.NotConnectedException

XMPPException.XMPPErrorException

SmackException.NoResponseException

InterruptedException

sendCarbonsEnabled

@Deprecated
public void sendCarbonsEnabled(boolean new_state)
                                    throws SmackException.NotConnectedException,
                                           InterruptedException

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

Throws:

SmackException.NotConnectedException

InterruptedException

enableCarbonsAsync

public void enableCarbonsAsync(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(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 SmackException.NoResponseException,
                              XMPPException.XMPPErrorException,
                              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:

XMPPException.XMPPErrorException

SmackException.NoResponseException

SmackException.NotConnectedException

InterruptedException

enableCarbons

public void enableCarbons()
                   throws XMPPException,
                          SmackException,
                          InterruptedException

Helper method to enable carbons.

Throws:

XMPPException

SmackException - if there was no response from the server.

InterruptedException

disableCarbons

public void disableCarbons()
                    throws XMPPException,
                           SmackException,
                           InterruptedException

Helper method to disable carbons.

Throws:

XMPPException

SmackException - if there was no response from the server.

InterruptedException

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(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